Plotting
********

Introduction to Plotting
========================

Earlier versions of Octave provided plotting through the use of gnuplot.  This capability is still available.  But, a newer plotting capability is provided by access to OpenGL.  Which plotting system is used is controlled by the graphics_toolkit function. See Graphics Toolkits.

The function call graphics_toolkit ("qt") selects the Qt/OpenGL system, graphics_toolkit ("fltk") selects the FLTK/OpenGL system, and graphics_toolkit ("gnuplot") selects the gnuplot system.  The three systems may be used selectively through the use of the graphics_toolkit property of the graphics handle for each figure.  This is explained in Graphics Data Structures. Caution: The OpenGL-based toolkits use single precision variables internally which limits the maximum value that can be displayed to approximately 10^38.  If your data contains larger values you must use the gnuplot toolkit which supports values up to 10^308.

High-Level Plotting
===================

Octave provides simple means to create many different types of two- and three-dimensional plots using high-level functions.

If you need more detailed control, see Graphics Data Structures and Advanced Plotting.

Two-Dimensional Plots
---------------------

The plot function allows you to create simple x-y plots with linear axes.  For example,

     x = -10:0.1:10;
     plot (x, sin (x));
     xlabel ("x");
     ylabel ("sin (x)");
     title ("Simple 2-D Plot");

displays a sine wave shown in fig:plot.  On most systems, this command will open a separate plot window to display the graph.

Figure: Simple Two-Dimensional Plot.

 -- plot: (Y)
 -- plot: (X, Y)
 -- plot: (X, Y, FMT)
 -- plot: (..., PROPERTY, VALUE, ...)
 -- plot: (X1, Y1, ..., XN, YN)
 -- plot: (HAX, ...)
 -- H =: plot (...)
     Produce 2-D plots.

     Many different combinations of arguments are possible.  The simplest form is

          plot (Y)

     where the argument is taken as the set of Y coordinates and the X coordinates are taken to be the range 1:numel (Y).

     If more than one argument is given, they are interpreted as

          plot (Y, PROPERTY, VALUE, ...)

     or

          plot (X, Y, PROPERTY, VALUE, ...)

     or

          plot (X, Y, FMT, ...)

     and so on.  Any number of argument sets may appear.  The X and Y values are interpreted as follows:

       * If a single data argument is supplied, it is taken as the set of Y coordinates and the X coordinates are taken to be the indices of the elements, starting with 1.

       * If X and Y are scalars, a single point is plotted.

       * squeeze() is applied to arguments with more than two dimensions, but no more than two singleton dimensions.

       * If both arguments are vectors, the elements of Y are plotted versus the elements of X.

       * If X is a vector and Y is a matrix, then the columns (or rows) of Y are plotted versus X. (using whichever combination matches, with columns tried first.)

       * If the X is a matrix and Y is a vector, Y is plotted versus the columns (or rows) of X. (using whichever combination matches, with columns tried first.)

       * If both arguments are matrices, the columns of Y are plotted versus the columns of X.  In this case, both matrices must have the same number of rows and columns and no attempt is made to transpose the arguments to make the number of rows match.

     Multiple property-value pairs may be specified, but they must appear in pairs.  These arguments are applied to the line objects drawn by plot.  Useful properties to modify are "linestyle", "linewidth", "color", "marker", "markersize", "markeredgecolor", "markerfacecolor". See Line Properties.

     The FMT format argument can also be used to control the plot style. It is a string composed of four optional parts: "<linestyle><marker><color><;displayname;>". When a marker is specified, but no linestyle, only the markers are plotted.  Similarly, if a linestyle is specified, but no marker, then only lines are drawn.  If both are specified then lines and markers will be plotted.  If no FMT and no PROPERTY/VALUE pairs are given, then the default plot style is solid lines with no markers and the color determined by the "colororder" property of the current axes.

     Format arguments:

     linestyle

          -    Use solid lines (default).
          --   Use dashed lines.
          :    Use dotted lines.
          -.   Use dash-dotted lines.

     marker

          +   crosshair
          o   circle
          *   star
          .   point
          x   cross
          s   square
          d   diamond
          ^   upward-facing triangle
          v   downward-facing triangle
          >   right-facing triangle
          <   left-facing triangle
          p   pentagram
          h   hexagram

     color

          k   blacK
          r   Red
          g   Green
          b   Blue
          y   Yellow
          m   Magenta
          c   Cyan
          w   White

     ";displayname;"
          Here "displayname" is the label to use for the plot legend.

     The FMT argument may also be used to assign legend labels. To do so, include the desired label between semicolons after the formatting sequence described above, e.g., "+b;Key Title;". Note that the last semicolon is required and Octave will generate an error if it is left out.

     Here are some plot examples:

          plot (x, y, "or", x, y2, x, y3, "m", x, y4, "+")

     This command will plot y with red circles, y2 with solid lines, y3 with solid magenta lines, and y4 with points displayed as +.

          plot (b, "*", "markersize", 10)

     This command will plot the data in the variable b, with points displayed as * and a marker size of 10.

          t = 0:0.1:6.3;
          plot (t, cos(t), "-;cos(t);", t, sin(t), "-b;sin(t);");

     This will plot the cosine and sine functions and label them accordingly in the legend.

     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 vector of graphics handles to the created line objects.

     To save a plot, in one of several image formats such as PostScript or PNG, use the print command.

     axis, box, grid, hold, legend, title, xlabel, ylabel, xlim, ylim, ezplot, errorbar, fplot, line, plot3, polar, loglog, semilogx, semilogy, subplot

The plotyy function may be used to create a plot with two independent y axes.

 -- plotyy: (X1, Y1, X2, Y2)
 -- plotyy: (..., FUN)
 -- plotyy: (..., FUN1, FUN2)
 -- plotyy: (HAX, ...)
 -- [AX, H1, H2] =: plotyy (...)
     Plot two sets of data with independent y-axes and a common x-axis.

     The arguments X1 and Y1 define the arguments for the first plot and X1 and Y2 for the second.

     By default the arguments are evaluated with feval (@plot, X, Y).  However the type of plot can be modified with the FUN argument, in which case the plots are generated by feval (FUN, X, Y).  FUN can be a function handle, an inline function, or a string of a function name.

     The function to use for each of the plots can be independently defined with FUN1 and FUN2.

     If the first argument HAX is an axes handle, then it defines the principal axes in which to plot the X1 and Y1 data.

     The return value AX is a vector with the axes handles of the two y-axes.  H1 and H2 are handles to the objects generated by the plot commands.

          x = 0:0.1:2*pi;
          y1 = sin (x);
          y2 = exp (x - 1);
          ax = plotyy (x, y1, x - 1, y2, @plot, @semilogy);
          xlabel ("X");
          ylabel (ax(1), "Axis 1");
          ylabel (ax(2), "Axis 2");

     plot

The functions semilogx, semilogy, and loglog are similar to the plot function, but produce plots in which one or both of the axes use log scales.

 -- semilogx: (Y)
 -- semilogx: (X, Y)
 -- semilogx: (X, Y, PROPERTY, VALUE, ...)
 -- semilogx: (X, Y, FMT)
 -- semilogx: (HAX, ...)
 -- H =: semilogx (...)
     Produce a 2-D plot using a logarithmic scale for the x-axis.

     See the documentation of plot for a description of the arguments that semilogx will accept.

     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 plot. plot, semilogy, loglog

 -- semilogy: (Y)
 -- semilogy: (X, Y)
 -- semilogy: (X, Y, PROPERTY, VALUE, ...)
 -- semilogy: (X, Y, FMT)
 -- semilogy: (H, ...)
 -- H =: semilogy (...)
     Produce a 2-D plot using a logarithmic scale for the y-axis.

     See the documentation of plot for a description of the arguments that semilogy will accept.

     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 plot. plot, semilogx, loglog

 -- loglog: (Y)
 -- loglog: (X, Y)
 -- loglog: (X, Y, PROP, VALUE, ...)
 -- loglog: (X, Y, FMT)
 -- loglog: (HAX, ...)
 -- H =: loglog (...)
     Produce a 2-D plot using logarithmic scales for both axes.

     See the documentation of plot for a description of the arguments that loglog will accept.

     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 plot. plot, semilogx, semilogy

The functions bar, barh, stairs, and stem are useful for displaying discrete data.  For example,

     randn ("state", 1);
     hist (randn (10000, 1), 30);
     xlabel ("Value");
     ylabel ("Count");
     title ("Histogram of 10,000 normally distributed random numbers");

produces the histogram of 10,000 normally distributed random numbers shown in fig:hist.  Note that, randn ("state", 1);, initializes the random number generator for randn to a known value so that the returned values are reproducible; This guarantees that the figure produced is identical to the one in this manual.

Figure: Histogram.

 -- bar: (Y)
 -- bar: (X, Y)
 -- bar: (..., W)
 -- bar: (..., STYLE)
 -- bar: (..., PROP, VAL, ...)
 -- bar: (HAX, ...)
 -- H =: bar (..., PROP, VAL, ...)
     Produce a bar graph from two vectors of X-Y data.

     If only one argument is given, Y, it is taken as a vector of Y values and the X coordinates are the range 1:numel (Y).

     The optional input W controls the width of the bars.  A value of 1.0 will cause each bar to exactly touch any adjacent bars. The default width is 0.8.

     If Y is a matrix, then each column of Y is taken to be a separate bar graph plotted on the same graph.  By default the columns are plotted side-by-side.  This behavior can be changed by the STYLE argument which can take the following values:

     "grouped" (default)
          Side-by-side bars with a gap between bars and centered over the X-coordinate.

     "stacked"
          Bars are stacked so that each X value has a single bar composed of multiple segments.

     "hist"
          Side-by-side bars with no gap between bars and centered over the X-coordinate.

     "histc"
          Side-by-side bars with no gap between bars and left-aligned to the X-coordinate.

     Optional property/value pairs are passed directly to the underlying patch objects.

     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 vector of handles to the created "bar series" hggroups with one handle per column of the variable Y. This series makes it possible to change a common element in one bar series object and have the change reflected in the other "bar series". For example,

          h = bar (rand (5, 10));
          set (h(1), "basevalue", 0.5);

     changes the position on the base of all of the bar series.

     The following example modifies the face and edge colors using property/value pairs.

          bar (randn (1, 100), "facecolor", "r", "edgecolor", "b");

     The color of the bars is taken from the figure's colormap, such that

          bar (rand (10, 3));
          colormap (summer (64));

     will change the colors used for the bars.  The color of bars can also be set manually using the "facecolor" property as shown below.

          h = bar (rand (10, 3));
          set (h(1), "facecolor", "r")
          set (h(2), "facecolor", "g")
          set (h(3), "facecolor", "b")

     barh, hist, pie, plot, patch

 -- barh: (Y)
 -- barh: (X, Y)
 -- barh: (..., W)
 -- barh: (..., STYLE)
 -- barh: (..., PROP, VAL, ...)
 -- barh: (HAX, ...)
 -- H =: barh (..., PROP, VAL, ...)
     Produce a horizontal bar graph from two vectors of X-Y data.

     If only one argument is given, it is taken as a vector of Y values and the X coordinates are the range 1:numel (Y).

     The optional input W controls the width of the bars.  A value of 1.0 will cause each bar to exactly touch any adjacent bars. The default width is 0.8.

     If Y is a matrix, then each column of Y is taken to be a separate bar graph plotted on the same graph.  By default the columns are plotted side-by-side.  This behavior can be changed by the STYLE argument which can take the following values:

     "grouped" (default)
          Side-by-side bars with a gap between bars and centered over the Y-coordinate.

     "stacked"
          Bars are stacked so that each Y value has a single bar composed of multiple segments.

     "hist"
          Side-by-side bars with no gap between bars and centered over the Y-coordinate.

     "histc"
          Side-by-side bars with no gap between bars and left-aligned to the Y-coordinate.

     Optional property/value pairs are passed directly to the underlying patch objects.

     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 bar series hggroup.  For a description of the use of the bar series, see bar. bar, hist, pie, plot, patch

 -- hist: (Y)
 -- hist: (Y, NBINS)
 -- hist: (Y, X)
 -- hist: (Y, X, NORM)
 -- hist: (..., PROP, VAL, ...)
 -- hist: (HAX, ...)
 -- [NN, XX] =: hist (...)
     Produce histogram counts or plots.

     With one vector input argument, Y, plot a histogram of the values with 10 bins.  The range of the histogram bins is determined by the range of the data (difference between maximum and minimum value in Y). Extreme values are lumped into the first and last bins.  If Y is a matrix then plot a histogram where each bin contains one bar per input column of Y.

     If the optional second argument is a scalar, NBINS, it defines the number of bins.

     If the optional second argument is a vector, X, it defines the centers of the bins.  The width of the bins is determined from the adjacent values in the vector.  The total number of bins is numel (X).

     If a third argument is provided, the histogram is normalized such that the sum of the bars is equal to NORM.

     The histogram's appearance may be modified by specifying property/value pairs.  For example, the face and edge color may be modified:

          hist (randn (1, 100), 25, "facecolor", "r", "edgecolor", "b");

     The histogram's colors also depend upon the current colormap.

          hist (rand (10, 3));
          colormap (summer ());

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

     If an output is requested then no plot is made.  Instead, return the values NN (numbers of elements) and XX (bin centers) such that bar (XX, NN) will plot the histogram.

     histc, bar, pie, rose

 -- stemleaf: (X, CAPTION)
 -- stemleaf: (X, CAPTION, STEM_SZ)
 -- PLOTSTR =: stemleaf (...)
     Compute and display a stem and leaf plot of the vector X.

     The input X should be a vector of integers.  Any non-integer values will be converted to integer by X = fix (X).  By default each element of X will be plotted with the last digit of the element as a leaf value and the remaining digits as the stem.  For example, 123 will be plotted with the stem 12 and the leaf 3.  The second argument, CAPTION, should be a character array which provides a description of the data.  It is included as a heading for the output.

     The optional input STEM_SZ sets the width of each stem. The stem width is determined by 10^(STEM_SZ + 1). The default stem width is 10.

     The output of stemleaf is composed of two parts: a "Fenced Letter Display," followed by the stem-and-leaf plot itself. The Fenced Letter Display is described in Exploratory Data Analysis. Briefly, the entries are as shown:

                  Fenced Letter Display
          #% nx|___________________     nx = numel (x)
          M% mi|       md         |     mi median index, md median
          H% hi|hl              hu| hs  hi lower hinge index, hl,hu hinges,
          1    |x(1)         x(nx)|     hs h_spreadx(1), x(nx) first
                     _______            and last data value.
               ______|step |_______     step 1.5*h_spread
              f|ifl            ifh|     inner fence, lower and higher
               |nfl            nfh|     no.\ of data points within fences
              F|ofl            ofh|     outer fence, lower and higher
               |nFl            nFh|     no.\ of data points outside outer
                                        fences

     The stem-and-leaf plot shows on each line the stem value followed by the string made up of the leaf digits.  If the STEM_SZ is not 1 the successive leaf values are separated by ",".

     With no return argument, the plot is immediately displayed.  If an output argument is provided, the plot is returned as an array of strings.

     The leaf digits are not sorted.  If sorted leaf values are desired, use XS = sort (X) before calling stemleaf (XS).

     The stem and leaf plot and associated displays are described in: Chapter 3, Exploratory Data Analysis by J. W. Tukey, Addison-Wesley, 1977. hist, printd

 -- printd: (OBJ, FILENAME)
 -- OUT_FILE =: printd (...)

     Convert any object acceptable to disp into the format selected by the suffix of FILENAME.

     If the return argument OUT_FILE is given, the name of the created file is returned.

     This function is intended to facilitate manipulation of the output of functions such as stemleaf. stemleaf

 -- stairs: (Y)
 -- stairs: (X, Y)
 -- stairs: (..., STYLE)
 -- stairs: (..., PROP, VAL, ...)
 -- stairs: (HAX, ...)
 -- H =: stairs (...)
 -- [XSTEP, YSTEP] =: stairs (...)
     Produce a stairstep plot.

     The arguments X and Y may be vectors or matrices. If only one argument is given, it is taken as a vector of Y values and the X coordinates are taken to be the indices of the elements (X = 1:numel (Y)).

     The style to use for the plot can be defined with a line style STYLE of the same format as the plot command.

     Multiple property/value pairs may be specified, but they must appear in pairs.

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

     If one output argument is requested, return a graphics handle to the created plot.  If two output arguments are specified, the data are generated but not plotted.  For example,

          stairs (x, y);

     and

          [xs, ys] = stairs (x, y);
          plot (xs, ys);

     are equivalent. bar, hist, plot, stem

 -- stem: (Y)
 -- stem: (X, Y)
 -- stem: (..., LINESPEC)
 -- stem: (..., "filled")
 -- stem: (..., PROP, VAL, ...)
 -- stem: (HAX, ...)
 -- H =: stem (...)
     Plot a 2-D stem graph.

     If only one argument is given, it is taken as the y-values and the x-coordinates are taken from the indices of the elements.

     If Y is a matrix, then each column of the matrix is plotted as a separate stem graph.  In this case X can either be a vector, the same length as the number of rows in Y, or it can be a matrix of the same size as Y.

     The default color is "b" (blue), the default line style is "-", and the default marker is "o".  The line style can be altered by the LINESPEC argument in the same manner as the plot command.  If the "filled" argument is present the markers at the top of the stems will be filled in.  For example,

          x = 1:10;
          y = 2*x;
          stem (x, y, "r");

     plots 10 stems with heights from 2 to 20 in red;

     Optional property/value pairs may be specified to control the appearance of the plot.

     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 handle to a "stem series" hggroup.  The single hggroup handle has all of the graphical elements comprising the plot as its children; This allows the properties of multiple graphics objects to be changed by modifying just a single property of the "stem series" hggroup.

     For example,

          x = [0:10]';
          y = [sin(x), cos(x)]
          h = stem (x, y);
          set (h(2), "color", "g");
          set (h(1), "basevalue", -1)

     changes the color of the second "stem series" and moves the base line of the first.

     Stem Series Properties

     linestyle
          The linestyle of the stem.  (Default: "-")

     linewidth
          The width of the stem.  (Default: 0.5)

     color
          The color of the stem, and if not separately specified, the marker. (Default: "b" [blue])

     marker
          The marker symbol to use at the top of each stem.  (Default: "o")

     markeredgecolor
          The edge color of the marker.  (Default: "color" property)

     markerfacecolor
          The color to use for "filling" the marker. (Default: "none" [unfilled])

     markersize
          The size of the marker.  (Default: 6)

     baseline
          The handle of the line object which implements the baseline.  Use set with the returned handle to change graphic properties of the baseline.

     basevalue
          The y-value where the baseline is drawn.  (Default: 0)

     stem3, bar, hist, plot, stairs

 -- stem3: (X, Y, Z)
 -- stem3: (..., LINESPEC)
 -- stem3: (..., "filled")
 -- stem3: (..., PROP, VAL, ...)
 -- stem3: (HAX, ...)
 -- H =: stem3 (...)
     Plot a 3-D stem graph.

     Stems are drawn from the height Z to the location in the x-y plane determined by X and Y.  The default color is "b" (blue), the default line style is "-", and the default marker is "o".

     The line style can be altered by the LINESPEC argument in the same manner as the plot command.  If the "filled" argument is present the markers at the top of the stems will be filled in.

     Optional property/value pairs may be specified to control the appearance of the plot.

     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 handle to the "stem series" hggroup containing the line and marker objects used for the plot. See stem, for a description of the "stem series" object.

     Example:

          theta = 0:0.2:6;
          stem3 (cos (theta), sin (theta), theta);

     plots 31 stems with heights from 0 to 6 lying on a circle.

     Implementation Note: Color definitions with RGB-triples are not valid. stem, bar, hist, plot

 -- scatter: (X, Y)
 -- scatter: (X, Y, S)
 -- scatter: (X, Y, S, C)
 -- scatter: (..., STYLE)
 -- scatter: (..., "filled")
 -- scatter: (..., PROP, VAL, ...)
 -- scatter: (HAX, ...)
 -- H =: scatter (...)
     Draw a 2-D scatter plot.

     A marker is plotted at each point defined by the coordinates in the vectors X and Y.

     The size of the markers is determined by S, which can be a scalar or a vector of the same length as X and Y.  If S is not given, or is an empty matrix, then a default value of 36 square points is used (The marker size itself is sqrt (s)).

     The color of the markers is determined by C, which can be a string defining a fixed color; a 3-element vector giving the red, green, and blue components of the color; a vector of the same length as X that gives a scaled index into the current colormap; or an Nx3 matrix defining the RGB color of each marker individually.

     The marker to use can be changed with the STYLE argument; it is a string defining a marker in the same manner as the plot command. If no marker is specified it defaults to "o" or circles. If the argument "filled" is given then the markers are filled.

     Additional property/value pairs are passed directly to the underlying patch 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 scatter object.

     Example:

          x = randn (100, 1);
          y = randn (100, 1);
          scatter (x, y, [], sqrt (x.^2 + y.^2));

     scatter3, patch, plot

 -- plotmatrix: (X, Y)
 -- plotmatrix: (X)
 -- plotmatrix: (..., STYLE)
 -- plotmatrix: (HAX, ...)
 -- [H, AX, BIGAX, P, PAX] =: plotmatrix (...)
     Scatter plot of the columns of one matrix against another.

     Given the arguments X and Y that have a matching number of rows, plotmatrix plots a set of axes corresponding to

          plot (X(:, i), Y(:, j))

     When called with a single argument X this is equivalent to

          plotmatrix (X, X)

     except that the diagonal of the set of axes will be replaced with the histogram hist (X(:, i)).

     The marker to use can be changed with the STYLE argument, that is a string defining a marker in the same manner as the plot command.

     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 provides handles to the individual graphics objects in the scatter plots, whereas AX returns the handles to the scatter plot axes objects.

     BIGAX is a hidden axes object that surrounds the other axes, such that the commands xlabel, title, etc., will be associated with this hidden axes.

     Finally, P returns the graphics objects associated with the histogram and PAX the corresponding axes objects.

     Example:

          plotmatrix (randn (100, 3), "g+")

     scatter, plot

 -- pareto: (Y)
 -- pareto: (Y, X)
 -- pareto: (HAX, ...)
 -- H =: pareto (...)
     Draw a Pareto chart.

     A Pareto chart is a bar graph that arranges information in such a way that priorities for process improvement can be established; It organizes and displays information to show the relative importance of data.  The chart is similar to the histogram or bar chart, except that the bars are arranged in decreasing magnitude from left to right along the x-axis.

     The fundamental idea (Pareto principle) behind the use of Pareto diagrams is that the majority of an effect is due to a small subset of the causes.  For quality improvement, the first few contributing causes (leftmost bars as presented on the diagram) to a problem usually account for the majority of the result.  Thus, targeting these "major causes" for elimination results in the most cost-effective improvement scheme.

     Typically only the magnitude data Y is present in which case X is taken to be the range 1 : length (Y).  If X is given it may be a string array, a cell array of strings, or a numerical vector.

     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 2-element vector with a graphics handle for the created bar plot and a second handle for the created line plot.

     An example of the use of pareto is

          Cheese = {"Cheddar", "Swiss", "Camembert", ...
                    "Munster", "Stilton", "Blue"};
          Sold = [105, 30, 70, 10, 15, 20];
          pareto (Sold, Cheese);

     bar, barh, hist, pie, plot

 -- rose: (TH)
 -- rose: (TH, NBINS)
 -- rose: (TH, BINS)
 -- rose: (HAX, ...)
 -- H =: rose (...)
 -- [THOUT ROUT] =: rose (...)
     Plot an angular histogram.

     With one vector argument, TH, plot the histogram with 20 angular bins. If TH is a matrix then each column of TH produces a separate histogram.

     If NBINS is given and is a scalar, then the histogram is produced with NBIN bins.  If BINS is a vector, then the center of each bin is defined by the values in BINS and the number of bins is given by the number of elements in BINS.

     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 vector of graphics handles to the line objects representing each histogram.

     If two output arguments are requested then no plot is made and the polar vectors necessary to plot the histogram are returned instead.

     Example

          [th, r] = rose ([2*randn(1e5,1), pi + 2*randn(1e5,1)]);
          polar (th, r);

     Programming Note: When specifying bin centers with the BINS input, the edges for bins 2 to N-1 are spaced so that BINS(i) is centered between the edges.  The final edge is drawn halfway between bin N and bin 1.  This guarantees that all input TH will be placed into one of the bins, but also means that for some combinations bin 1 and bin N may not be centered on the user's given values. hist, polar

The contour, contourf and contourc functions produce two-dimensional contour plots from three-dimensional data.

 -- contour: (Z)
 -- contour: (Z, VN)
 -- contour: (X, Y, Z)
 -- contour: (X, Y, Z, VN)
 -- contour: (..., STYLE)
 -- contour: (HAX, ...)
 -- [C, H] =: contour (...)
     Create a 2-D contour plot.

     Plot level curves (contour lines) of the matrix Z, using the contour matrix C computed by contourc from the same arguments; see the latter for their interpretation.

     The appearance of contour lines can be defined with a line style STYLE in the same manner as plot.  Only line style and color are used; Any markers defined by STYLE are ignored.

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

     The optional output C contains the contour levels in contourc format.

     The optional return value H is a graphics handle to the hggroup comprising the contour lines.

     Example:

          x = 0:2;
          y = x;
          z = x' * y;
          contour (x, y, z, 2:3)

     ezcontour, contourc, contourf, contour3, clabel, meshc, surfc, caxis, colormap, plot

 -- contourf: (Z)
 -- contourf: (Z, VN)
 -- contourf: (X, Y, Z)
 -- contourf: (X, Y, Z, VN)
 -- contourf: (..., STYLE)
 -- contourf: (HAX, ...)
 -- [C, H] =: contourf (...)
     Create a 2-D contour plot with filled intervals.

     Plot level curves (contour lines) of the matrix Z and fill the region between lines with colors from the current colormap.

     The level curves are taken from the contour matrix C computed by contourc for the same arguments; see the latter for their interpretation.

     The appearance of contour lines can be defined with a line style STYLE in the same manner as plot.  Only line style and color are used; Any markers defined by STYLE are ignored.

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

     The optional output C contains the contour levels in contourc format.

     The optional return value H is a graphics handle to the hggroup comprising the contour lines.

     The following example plots filled contours of the peaks function.

          [x, y, z] = peaks (50);
          contourf (x, y, z, -7:9)

     ezcontourf, contour, contourc, contour3, clabel, meshc, surfc, caxis, colormap, plot

 -- [C, LEV] =: contourc (Z)
 -- [C, LEV] =: contourc (Z, VN)
 -- [C, LEV] =: contourc (X, Y, Z)
 -- [C, LEV] =: contourc (X, Y, Z, VN)
     Compute contour lines (isolines of constant Z value).

     The matrix Z contains height values above the rectangular grid determined by X and Y.  If only a single input Z is provided then X is taken to be 1:columns (Z) and Y is taken to be 1:rows (Z).

     The optional input VN is either a scalar denoting the number of contour lines to compute or a vector containing the Z values where lines will be computed.  When VN is a vector the number of contour lines is numel (VN).  However, to compute a single contour line at a given value use VN = [val, val].  If VN is omitted it defaults to 10.

     The return value C is a 2xN matrix containing the contour lines in the following format

          C = [lev1, x1, x2, ..., levn, x1, x2, ...
               len1, y1, y2, ..., lenn, y1, y2, ...]

     in which contour line N has a level (height) of LEVN and length of LENN.

     The optional return value LEV is a vector with the Z values of the contour levels.

     Example:

          x = 0:2;
          y = x;
          z = x' * y;
          contourc (x, y, z, 2:3)
             =>   2.0000   2.0000   1.0000   3.0000   1.5000   2.0000
                  2.0000   1.0000   2.0000   2.0000   2.0000   1.5000

     contour, contourf, contour3, clabel

 -- contour3: (Z)
 -- contour3: (Z, VN)
 -- contour3: (X, Y, Z)
 -- contour3: (X, Y, Z, VN)
 -- contour3: (..., STYLE)
 -- contour3: (HAX, ...)
 -- [C, H] =: contour3 (...)
     Create a 3-D contour plot.

     contour3 plots level curves (contour lines) of the matrix Z at a Z level corresponding to each contour.  This is in contrast to contour which plots all of the contour lines at the same Z level and produces a 2-D plot.

     The level curves are taken from the contour matrix C computed by contourc for the same arguments; see the latter for their interpretation.

     The appearance of contour lines can be defined with a line style STYLE in the same manner as plot.  Only line style and color are used; Any markers defined by STYLE are ignored.

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

     The optional output C are the contour levels in contourc format.

     The optional return value H is a graphics handle to the hggroup comprising the contour lines.

     Example:

          contour3 (peaks (19));
          colormap cool;
          hold on;
          surf (peaks (19), "facecolor", "none", "edgecolor", "black");

     contour, contourc, contourf, clabel, meshc, surfc, caxis, colormap, plot

The errorbar, semilogxerr, semilogyerr, and loglogerr functions produce plots with error bar markers.  For example,

     rand ("state", 2);
     x = 0:0.1:10;
     y = sin (x);
     lerr = 0.1 .* rand (size (x));
     uerr = 0.1 .* rand (size (x));
     errorbar (x, y, lerr, uerr);
     axis ([0, 10, -1.1, 1.1]);
     xlabel ("x");
     ylabel ("sin (x)");
     title ("Errorbar plot of sin (x)");

produces the figure shown in fig:errorbar.

Figure: Errorbar plot.

 -- errorbar: (Y, EY)
 -- errorbar: (Y, ..., FMT)
 -- errorbar: (X, Y, EY)
 -- errorbar: (X, Y, ERR, FMT)
 -- errorbar: (X, Y, LERR, UERR, FMT)
 -- errorbar: (X, Y, EX, EY, FMT)
 -- errorbar: (X, Y, LX, UX, LY, UY, FMT)
 -- errorbar: (X1, Y1, ..., FMT, XN, YN, ...)
 -- errorbar: (HAX, ...)
 -- H =: errorbar (...)
     Create a 2-D plot with errorbars.

     Many different combinations of arguments are possible.  The simplest form is

          errorbar (Y, EY)

     where the first argument is taken as the set of Y coordinates, the second argument EY are the errors around the Y values, and the X coordinates are taken to be the indices of the elements (1:numel (Y)).

     The general form of the function is

          errorbar (X, Y, ERR1, ..., FMT, ...)

     After the X and Y arguments there can be 1, 2, or 4 parameters specifying the error values depending on the nature of the error values and the plot format FMT.

     ERR (scalar)
          When the error is a scalar all points share the same error value. The errorbars are symmetric and are drawn from DATA-ERR to DATA+ERR. The FMT argument determines whether ERR is in the x-direction, y-direction (default), or both.

     ERR (vector or matrix)
          Each data point has a particular error value. The errorbars are symmetric and are drawn from DATA(n)-ERR(n) to DATA(n)+ERR(n).

     LERR, UERR (scalar)
          The errors have a single low-side value and a single upper-side value. The errorbars are not symmetric and are drawn from DATA-LERR to DATA+UERR.

     LERR, UERR (vector or matrix)
          Each data point has a low-side error and an upper-side error. The errorbars are not symmetric and are drawn from DATA(n)-LERR(n) to DATA(n)+UERR(n).

     Any number of data sets (X1,Y1, X2,Y2, ...) may appear as long as they are separated by a format string FMT.

     If Y is a matrix, X and the error parameters must also be matrices having the same dimensions.  The columns of Y are plotted versus the corresponding columns of X and errorbars are taken from the corresponding columns of the error parameters.

     If FMT is missing, the yerrorbars ("~") plot style is assumed.

     If the FMT argument is supplied then it is interpreted, as in normal plots, to specify the line style, marker, and color.  In addition, FMT may include an errorbar style which must precede the ordinary format codes.  The following errorbar styles are supported:

     ~
          Set yerrorbars plot style (default).

     >
          Set xerrorbars plot style.

     ~>
          Set xyerrorbars plot style.

     #~
          Set yboxes plot style.

     #
          Set xboxes plot style.

     #~>
          Set xyboxes plot style.

     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 handle to the hggroup object representing the data plot and errorbars.

     Note: For compatibility with MATLAB a line is drawn through all data points.  However, most scientific errorbar plots are a scatter plot of points with errorbars.  To accomplish this, add a marker style to the FMT argument such as ".".  Alternatively, remove the line by modifying the returned graphic handle with set (h, "linestyle", "none").

     Examples:

          errorbar (X, Y, EX, ">.r")

     produces an xerrorbar plot of Y versus X with X errorbars drawn from X-EX to X+EX.  The marker "." is used so no connecting line is drawn and the errorbars appear in red.

          errorbar (X, Y1, EY, "~",
                    X, Y2, LY, UY)

     produces yerrorbar plots with Y1 and Y2 versus X. Errorbars for Y1 are drawn from Y1-EY to Y1+EY, errorbars for Y2 from Y2-LY to Y2+UY.

          errorbar (X, Y, LX, UX,
                    LY, UY, "~>")

     produces an xyerrorbar plot of Y versus X in which X errorbars are drawn from X-LX to X+UX and Y errorbars from Y-LY to Y+UY. semilogxerr, semilogyerr, loglogerr, plot

 -- semilogxerr: (Y, EY)
 -- semilogxerr: (Y, ..., FMT)
 -- semilogxerr: (X, Y, EY)
 -- semilogxerr: (X, Y, ERR, FMT)
 -- semilogxerr: (X, Y, LERR, UERR, FMT)
 -- semilogxerr: (X, Y, EX, EY, FMT)
 -- semilogxerr: (X, Y, LX, UX, LY, UY, FMT)
 -- semilogxerr: (X1, Y1, ..., FMT, XN, YN, ...)
 -- semilogxerr: (HAX, ...)
 -- H =: semilogxerr (...)
     Produce 2-D plots using a logarithmic scale for the x-axis and errorbars at each data point.

     Many different combinations of arguments are possible.  The most common form is

          semilogxerr (X, Y, EY, FMT)

     which produces a semi-logarithmic plot of Y versus X with errors in the Y-scale defined by EY and the plot format defined by FMT.  See errorbar, for available formats and additional information.

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

     errorbar, semilogyerr, loglogerr

 -- semilogyerr: (Y, EY)
 -- semilogyerr: (Y, ..., FMT)
 -- semilogyerr: (X, Y, EY)
 -- semilogyerr: (X, Y, ERR, FMT)
 -- semilogyerr: (X, Y, LERR, UERR, FMT)
 -- semilogyerr: (X, Y, EX, EY, FMT)
 -- semilogyerr: (X, Y, LX, UX, LY, UY, FMT)
 -- semilogyerr: (X1, Y1, ..., FMT, XN, YN, ...)
 -- semilogyerr: (HAX, ...)
 -- H =: semilogyerr (...)
     Produce 2-D plots using a logarithmic scale for the y-axis and errorbars at each data point.

     Many different combinations of arguments are possible.  The most common form is

          semilogyerr (X, Y, EY, FMT)

     which produces a semi-logarithmic plot of Y versus X with errors in the Y-scale defined by EY and the plot format defined by FMT.  See errorbar, for available formats and additional information.

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

     errorbar, semilogxerr, loglogerr

 -- loglogerr: (Y, EY)
 -- loglogerr: (Y, ..., FMT)
 -- loglogerr: (X, Y, EY)
 -- loglogerr: (X, Y, ERR, FMT)
 -- loglogerr: (X, Y, LERR, UERR, FMT)
 -- loglogerr: (X, Y, EX, EY, FMT)
 -- loglogerr: (X, Y, LX, UX, LY, UY, FMT)
 -- loglogerr: (X1, Y1, ..., FMT, XN, YN, ...)
 -- loglogerr: (HAX, ...)
 -- H =: loglogerr (...)
     Produce 2-D plots on a double logarithm axis with errorbars.

     Many different combinations of arguments are possible.  The most common form is

          loglogerr (X, Y, EY, FMT)

     which produces a double logarithm plot of Y versus X with errors in the Y-scale defined by EY and the plot format defined by FMT.  See errorbar, for available formats and additional information.

     If the first argument HAX is an axes handle, then plot into this axes, rather than the current axes returned by gca. errorbar, semilogxerr, semilogyerr

Finally, the polar function allows you to easily plot data in polar coordinates.  However, the display coordinates remain rectangular and linear.  For example,

     polar (0:0.1:10*pi, 0:0.1:10*pi);
     title ("Example polar plot from 0 to 10*pi");

produces the spiral plot shown in fig:polar.

Figure: Polar plot.

 -- polar: (THETA, RHO)
 -- polar: (THETA, RHO, FMT)
 -- polar: (CPLX)
 -- polar: (CPLX, FMT)
 -- polar: (HAX, ...)
 -- H =: polar (...)
     Create a 2-D plot from polar coordinates THETA and RHO.

     If a single complex input CPLX is given then the real part is used for THETA and the imaginary part is used for RHO.

     The optional argument FMT specifies the line format in the same way as plot.

     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 plot.

     Implementation Note: The polar axis is drawn using line and text objects encapsulated in an hggroup.  The hggroup properties are linked to the original axes object such that altering an appearance property, for example fontname, will update the polar axis.  Two new properties are added to the original axes--rtick, ttick--which replace xtick, ytick.  The first is a list of tick locations in the radial (rho) direction; The second is a list of tick locations in the angular (theta) direction specified in degrees, i.e., in the range 0--359. rose, compass, plot

 -- pie: (X)
 -- pie: (..., EXPLODE)
 -- pie: (..., LABELS)
 -- pie: (HAX, ...);
 -- H =: pie (...);
     Plot a 2-D pie chart.

     When called with a single vector argument, produce a pie chart of the elements in X.  The size of the ith slice is the percentage that the element Xi represents of the total sum of X: pct = X(i) / sum (X).

     The optional input EXPLODE is a vector of the same length as X that, if nonzero, "explodes" the slice from the pie chart.

     The optional input LABELS is a cell array of strings of the same length as X specifying the label for each slice.

     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 list of handles to the patch and text objects generating the plot.

     Note: If sum (X) ≤ 1 then the elements of X are interpreted as percentages directly and are not normalized by sum (x).  Furthermore, if the sum is less than 1 then there will be a missing slice in the pie plot to represent the missing, unspecified percentage.

     pie3, bar, hist, rose

 -- pie3: (X)
 -- pie3: (..., EXPLODE)
 -- pie3: (..., LABELS)
 -- pie3: (HAX, ...);
 -- H =: pie3 (...);
     Plot a 3-D pie chart.

     Called with a single vector argument, produces a 3-D pie chart of the elements in X.  The size of the ith slice is the percentage that the element Xi represents of the total sum of X: pct = X(i) / sum (X).

     The optional input EXPLODE is a vector of the same length as X that, if nonzero, "explodes" the slice from the pie chart.

     The optional input LABELS is a cell array of strings of the same length as X specifying the label for each slice.

     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 list of graphics handles to the patch, surface, and text objects generating the plot.

     Note: If sum (X) ≤ 1 then the elements of X are interpreted as percentages directly and are not normalized by sum (x).  Furthermore, if the sum is less than 1 then there will be a missing slice in the pie plot to represent the missing, unspecified percentage.

     pie, bar, hist, rose

 -- quiver: (U, V)
 -- quiver: (X, Y, U, V)
 -- quiver: (..., S)
 -- quiver: (..., STYLE)
 -- quiver: (..., "filled")
 -- quiver: (HAX, ...)
 -- H =: quiver (...)

     Plot a 2-D vector field with arrows.

     Plot the (U, V) components of a vector field at the grid points defined by (X, Y).  If the grid is uniform then X and Y can be specified as vectors and meshgrid is used to create the 2-D grid.

     If X and Y are not given they are assumed to be (1:M, 1:N) where [M, N] = size (U).

     The optional input S is a scalar defining a scaling factor to use for the arrows of the field relative to the mesh spacing.  A value of 1.0 will result in the longest vector exactly filling one grid square.  A value of 0 disables all scaling.  The default value is 0.9.

     The style to use for the plot can be defined with a line style STYLE of the same format as the plot command.  If a marker is specified then the markers are drawn at the origin of the vectors (which are the grid points defined by X and Y).  When a marker is specified, the arrowhead is not drawn.  If the argument "filled" is given then the markers are filled.

     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 a quiver object. A quiver object regroups the components of the quiver plot (body, arrow, and marker), and allows them to be changed together.

     Example:

          [x, y] = meshgrid (1:2:20);
          h = quiver (x, y, sin (2*pi*x/10), sin (2*pi*y/10));
          set (h, "maxheadsize", 0.33);

     quiver3, compass, feather, plot

 -- quiver3: (U, V, W)
 -- quiver3: (X, Y, Z, U, V, W)
 -- quiver3: (..., S)
 -- quiver3: (..., STYLE)
 -- quiver3: (..., "filled")
 -- quiver3: (HAX, ...)
 -- H =: quiver3 (...)

     Plot a 3-D vector field with arrows.

     Plot the (U, V, W) components of a vector field at the grid points defined by (X, Y, Z).  If the grid is uniform then X, Y, and Z can be specified as vectors and meshgrid is used to create the 3-D grid.

     If X, Y, and Z are not given they are assumed to be (1:M, 1:N, 1:P) where [M, N] = size (U) and P = max (size (W)).

     The optional input S is a scalar defining a scaling factor to use for the arrows of the field relative to the mesh spacing.  A value of 1.0 will result in the longest vector exactly filling one grid cube.  A value of 0 disables all scaling.  The default value is 0.9.

     The style to use for the plot can be defined with a line style STYLE of the same format as the plot command.  If a marker is specified then the markers are drawn at the origin of the vectors (which are the grid points defined by X, Y, Z).  When a marker is specified, the arrowhead is not drawn.  If the argument "filled" is given then the markers are filled.

     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 a quiver object. A quiver object regroups the components of the quiver plot (body, arrow, and marker), and allows them to be changed together.

          [x, y, z] = peaks (25);
          surf (x, y, z);
          hold on;
          [u, v, w] = surfnorm (x, y, z / 10);
          h = quiver3 (x, y, z, u, v, w);
          set (h, "maxheadsize", 0.33);

     quiver, compass, feather, plot

 -- compass: (U, V)
 -- compass: (Z)
 -- compass: (..., STYLE)
 -- compass: (HAX, ...)
 -- H =: compass (...)

     Plot the (U, V) components of a vector field emanating from the origin of a polar plot.

     The arrow representing each vector has one end at the origin and the tip at [U(i), V(i)].  If a single complex argument Z is given, then U = real (Z) and V = imag (Z).

     The style to use for the plot can be defined with a line style STYLE of the same format as the plot command.

     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 vector of graphics handles to the line objects representing the drawn vectors.

          a = toeplitz ([1;randn(9,1)], [1,randn(1,9)]);
          compass (eig (a));

     polar, feather, quiver, rose, plot

 -- feather: (U, V)
 -- feather: (Z)
 -- feather: (..., STYLE)
 -- feather: (HAX, ...)
 -- H =: feather (...)

     Plot the (U, V) components of a vector field emanating from equidistant points on the x-axis.

     If a single complex argument Z is given, then U = real (Z) and V = imag (Z).

     The style to use for the plot can be defined with a line style STYLE of the same format as the plot command.

     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 vector of graphics handles to the line objects representing the drawn vectors.

          phi = [0 : 15 : 360] * pi/180;
          feather (sin (phi), cos (phi));

     plot, quiver, compass

 -- pcolor: (X, Y, C)
 -- pcolor: (C)
 -- pcolor: (HAX, ...)
 -- H =: pcolor (...)
     Produce a 2-D density plot.

     A pcolor plot draws rectangles with colors from the matrix C over the two-dimensional region represented by the matrices X and Y.  X and Y are the coordinates of the mesh's vertices and are typically the output of meshgrid.  If X and Y are vectors, then a typical vertex is (X(j), Y(i), C(i,j)). Thus, columns of C correspond to different X values and rows of C correspond to different Y values.

     The values in C are scaled to span the range of the current colormap.  Limits may be placed on the color axis by the command caxis, or by setting the clim property of the parent axis.

     The face color of each cell of the mesh is determined by interpolating the values of C for each of the cell's vertices; Contrast this with imagesc which renders one cell for each element of C.

     shading modifies an attribute determining the manner by which the face color of each cell is interpolated from the values of C, and the visibility of the cells' edges.  By default the attribute is "faceted", which renders a single color for each cell's face with the edge visible.

     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.

     caxis, shading, meshgrid, contour, imagesc

 -- area: (Y)
 -- area: (X, Y)
 -- area: (..., LVL)
 -- area: (..., PROP, VAL, ...)
 -- area: (HAX, ...)
 -- H =: area (...)
     Area plot of the columns of Y.

     This plot shows the contributions of each column value to the row sum. It is functionally similar to plot (X, cumsum (Y, 2)), except that the area under the curve is shaded.

     If the X argument is omitted it defaults to 1:rows (Y). A value LVL can be defined that determines where the base level of the shading under the curve should be defined.  The default level is 0.

     Additional property/value pairs are passed directly to the underlying patch 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 hggroup object comprising the area patch objects.  The "BaseValue" property of the hggroup can be used to adjust the level where shading begins.

     Example: Verify identity sin^2 + cos^2 = 1

          t = linspace (0, 2*pi, 100)';
          y = [sin(t).^2, cos(t).^2];
          area (t, y);
          legend ("sin^2", "cos^2", "location", "NorthEastOutside");

     plot, patch

 -- fill: (X, Y, C)
 -- fill: (X1, Y1, C1, X2, Y2, C2)
 -- fill: (..., PROP, VAL)
 -- fill: (HAX, ...)
 -- H =: fill (...)
     Create one or more filled 2-D polygons.

     The inputs X and Y are the coordinates of the polygon vertices. If the inputs are matrices then the rows represent different vertices and each column produces a different polygon.  fill will close any open polygons before plotting.

     The input C determines the color of the polygon.  The simplest form is a single color specification such as a plot format or an RGB-triple.  In this case the polygon(s) will have one unique color.  If C is a vector or matrix then the color data is first scaled using caxis and then indexed into the current colormap.  A row vector will color each polygon (a column from matrices X and Y) with a single computed color.  A matrix C of the same size as X and Y will compute the color of each vertex and then interpolate the face color between the vertices.

     Multiple property/value pairs for the underlying patch object may be specified, but they must appear in pairs.

     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 vector of graphics handles to the created patch objects.

     Example: red square

          vertices = [0 0
                      1 0
                      1 1
                      0 1];
          fill (vertices(:,1), vertices(:,2), "r");
          axis ([-0.5 1.5, -0.5 1.5])
          axis equal

     patch, caxis, colormap

 -- comet: (Y)
 -- comet: (X, Y)
 -- comet: (X, Y, P)
 -- comet: (HAX, ...)
     Produce a simple comet style animation along the trajectory provided by the input coordinate vectors (X, Y).

     If X is not specified it defaults to the indices of Y.

     The speed of the comet may be controlled by P, which represents the time each point is displayed before moving to the next one.  The default for P is 0.1 seconds.

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

 -- comet3: (Z)
 -- comet3: (X, Y, Z)
 -- comet3: (X, Y, Z, P)
 -- comet3: (HAX, ...)
     Produce a simple comet style animation along the trajectory provided by the input coordinate vectors (X, Y, Z).

     If only Z is specified then X, Y default to the indices of Z.

     The speed of the comet may be controlled by P, which represents the time each point is displayed before moving to the next one.  The default for P is 0.1 seconds.

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

Axis Configuration
..................

The axis function may be used to change the axis limits of an existing plot and various other axis properties, such as the aspect ratio and the appearance of tic marks.

 -- axis: ()
 -- axis: ([X_LO X_HI])
 -- axis: ([X_LO X_HI Y_LO Y_HI])
 -- axis: ([X_LO X_HI Y_LO Y_HI Z_LO Z_HI])
 -- axis: ([X_LO X_HI Y_LO Y_HI Z_LO Z_HI C_LO C_HI])
 -- axis: (OPTION)
 -- axis: (OPTION1, OPTION2, ...)
 -- axis: (HAX, ...)
 -- LIMITS =: axis ()
     Set axis limits and appearance.

     The argument LIMITS should be a 2-, 4-, 6-, or 8-element vector.  The first and second elements specify the lower and upper limits for the x-axis.  The third and fourth specify the limits for the y-axis, the fifth and sixth specify the limits for the z-axis, and the seventh and eighth specify the limits for the color axis.  The special values -Inf and Inf may be used to indicate that the limit should be automatically computed based on the data in the axes.

     Without any arguments, axis turns autoscaling on.

     With one output argument, LIMITS = axis returns the current axis limits.

     The vector argument specifying limits is optional, and additional string arguments may be used to specify various axis properties.

     The following options control the aspect ratio of the axes.

     "square"
          Force a square axis aspect ratio.

     "equal"
          Force x-axis unit distance to equal y-axis (and z-axis) unit distance.

     "normal"
          Restore default aspect ratio.

     The following options control the way axis limits are interpreted.

     "auto"
     "auto[xyz]"
          Set the specified axes to have nice limits around the data or all if no axes are specified.

     "manual"
          Fix the current axes limits.

     "tight"
          Fix axes to the limits of the data.

     "image"
          Equivalent to "tight" and "equal".

     "vis3d"
          Set aspect ratio modes to "manual" for rotation without stretching.

     The following options affect the appearance of tick marks.

     "tic[xyz]"
          Turn tick marks on for all axes, or turn them on for the specified axes and off for the remainder.

     "label[xyz]"
          Turn tick labels on for all axes, or turn them on for the specified axes and off for the remainder.

     "nolabel"
          Turn tick labels off for all axes.

     Note: If there are no tick marks for an axes then there can be no labels.

     The following options affect the direction of increasing values on the axes.

     "xy"
          Default y-axis, larger values are near the top.

     "ij"
          Reverse y-axis, smaller values are near the top.

     The following options affects the visibility of the axes.

     "on"
          Make the axes visible.

     "off"
          Hide the axes.

     If the first argument HAX is an axes handle, then operate on this axes rather than the current axes returned by gca.

     Example 1: set X/Y limits and force a square aspect ratio

          axis ([1, 2, 3, 4], "square");

     Example 2: enable tick marks on all axes, enable tick mark labels only on the y-axis

          axis ("tic", "labely");

     xlim, ylim, zlim, caxis, daspect, pbaspect, box, grid

Similarly the axis limits of the colormap can be changed with the caxis function.

 -- caxis: ([cmin cmax])
 -- caxis: ("auto")
 -- caxis: ("manual")
 -- caxis: (HAX, ...)
 -- LIMITS =: caxis ()
     Query or set color axis limits for plots.

     The limits argument should be a 2-element vector specifying the lower and upper limits to assign to the first and last value in the colormap.  Data values outside this range are clamped to the first and last colormap entries.

     If the "auto" option is given then automatic colormap limits are applied.  The automatic algorithm sets CMIN to the minimum data value and CMAX to the maximum data value.  If "manual" is specified then the "climmode" property is set to "manual" and the numeric values in the "clim" property are used for limits.

     If the first argument HAX is an axes handle, then operate on this axes rather than the current axes returned by gca.

     Called without arguments the current color axis limits are returned.

     Programming Note: The color axis affects the display of image, patch, and surface graphics objects, but only if the "cdata" property has indexed data and the "cdatamapping" property is set to "scaled".  Graphic objects with true color cdata, or "direct" cdatamapping are not affected. colormap, axis

The xlim, ylim, and zlim functions may be used to get or set individual axis limits.  Each has the same form.

 -- XLIMITS =: xlim ()
 -- XMODE =: xlim ("mode")
 -- xlim: ([X_LO X_HI])
 -- xlim: ("auto")
 -- xlim: ("manual")
 -- xlim: (HAX, ...)
     Query or set the limits of the x-axis for the current plot.

     Called without arguments xlim returns the x-axis limits of the current plot.

     With the input query "mode", return the current x-limit calculation mode which is either "auto" or "manual".

     If passed a 2-element vector [X_LO X_HI], the limits of the x-axis are set to these values and the mode is set to "manual". The special values -Inf and Inf can be used to indicate that either the lower axis limit or upper axis limit should be automatically calculated.

     The current plotting mode can be changed by using either "auto" or "manual" as the argument.

     If the first argument HAX is an axes handle, then operate on this axes rather than the current axes returned by gca.

     Programming Note: The xlim function operates by modifying the "xlim" and "xlimmode" properties of an axes object.  These properties can be directly inspected and altered with get/set. ylim, zlim, axis, set, get, gca

The xticks, yticks, zticks, rticks, and thetaticks functions may be used to get or set the tick mark locations and modes on the respective axis.  Each has the same form, although mode options are not currently available for rticks, and thetaticks.

 -- TICKVAL =: xticks
 -- MODE =: xticks ("mode")
 -- xticks: (TICKVAL)
 -- xticks: ("auto")
 -- xticks: ("manual")
 -- ... =: xticks (HAX, ...)
     Query or set the tick values on the x-axis of the current axis.

     When called without an argument, return the current tick locations as specified in the "xtick" axes property.  These locations can be changed by calling xticks with a vector of tick values.  Note: ascending order is not required.

     When called with argument "mode", xticks returns the current value of the axes property "xtickmode".  This property can be changed by calling xticks with either "auto" (algorithm determines tick positions) or "manual" (tick values remain fixed regardless of axes resizing or rotation).  Note: Specifying xtick values will also set the property "xtickmode" to "manual".

     If the first argument HAX is an axes handle, then operate on this axis rather than the current axes returned by gca.

     Requesting a return value when calling xticks to set a property value will result in an error.

     xticklabels, yticks, zticks, rticks, thetaticks, get, set

The xticklabels, yticklabels, and zticklabels functions may be used to get or set the label assigned to each tick location and the labeling mode on the respective axis.  Each has the same form.

 -- TICKVAL =: xticklabels
 -- MODE =: xticklabels ("mode")
 -- xticklabels: (TICKVAL)
 -- xticklabels: ("auto")
 -- xticklabels: ("manual")
 -- ... =: xticklabels (HAX, ...)
     Query or set the tick labels on the x-axis of the current axis.

     When called without an argument, return a cell array of strings of the current tick labels as specified in the "xticklabel" axes property. These labels can be changed by calling xticklabels with a cell array of strings.  Note: a vector of numbers will be mapped to a cell array of strings.  If fewer labels are specified than the current number of ticks, blank labels will be appended to the array.

     When called with argument "mode", xticklabels returns the current value of the axes property "xticklabelmode".  This property can be changed by calling xticklabels with either "auto" (algorithm determines tick labels) or "manual" (tick labels remain fixed).  Note: Specifying xticklabel values will also set the "xticklabelmode" and "xticks" properties to "manual".

     If the first argument HAX is an axes handle, then operate on this axis rather than the current axes returned by gca.

     Requesting a return value when calling xticklabels to set a property value will result in an error.

     xticks, yticklabels, zticklabels, get, set

Two-dimensional Function Plotting
.................................

Octave can plot a function from a function handle, inline function, or string defining the function without the user needing to explicitly create the data to be plotted.  The function fplot also generates two-dimensional plots with linear axes using a function name and limits for the range of the x-coordinate instead of the x and y data.  For example,

     fplot (@sin, [-10, 10], 201);

produces a plot that is equivalent to the one above, but also includes a legend displaying the name of the plotted function.

 -- fplot: (FN, LIMITS)
 -- fplot: (..., TOL)
 -- fplot: (..., N)
 -- fplot: (..., FMT)
 -- [X, Y] =: fplot (...)
     Plot a function FN within the range defined by LIMITS.

     FN is a function handle, inline function, or string containing the name of the function to evaluate.

     The limits of the plot are of the form [XLO, XHI] or [XLO, XHI, YLO, YHI].

     The next three arguments are all optional and any number of them may be given in any order.

     TOL is the relative tolerance to use for the plot and defaults to 2e-3 (.2%).

     N is the minimum number of points to use.  When N is specified, the maximum stepsize will be (XHI - XLO) / N.  More than N points may still be used in order to meet the relative tolerance requirement.

     The FMT argument specifies the linestyle to be used by the plot command.

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

     With no output arguments the results are immediately plotted.  With two output arguments the 2-D plot data is returned.  The data can subsequently be plotted manually with plot (X, Y).

     Example:

          fplot (@cos, [0, 2*pi])
          fplot ("[cos(x), sin(x)]", [0, 2*pi])

     Programming Notes:

     fplot works best with continuous functions.  Functions with discontinuities are unlikely to plot well.  This restriction may be removed in the future.

     fplot performance is better when the function accepts and returns a vector argument.  Consider this when writing user-defined functions and use element-by-element operators such as .*, ./, etc.  See the function vectorize for potentially converting inline or anonymous functions to vectorized versions.

     ezplot, plot, vectorize

Other functions that can create two-dimensional plots directly from a function include ezplot, ezcontour, ezcontourf and ezpolar.

 -- ezplot: (F)
 -- ezplot: (F2V)
 -- ezplot: (FX, FY)
 -- ezplot: (..., DOM)
 -- ezplot: (..., N)
 -- ezplot: (HAX, ...)
 -- H =: ezplot (...)

     Plot the 2-D curve defined by the function F.

     The function F may be a string, inline function, or function handle and can have either one or two variables.  If F has one variable, then the function is plotted over the domain -2*pi < X < 2*pi with 500 points.

     If F2V is a function of two variables then the implicit function F(X,Y) = 0 is calculated over the meshed domain -2*pi <= X | Y <= 2*pi with 60 points in each dimension.

     For example:

          ezplot (@(X, Y) X.^2 - Y.^2 - 1)

     If two functions are passed as inputs then the parametric function

          X = FX (T)
          Y = FY (T)

     is plotted over the domain -2*pi <= T <= 2*pi with 500 points.

     If DOM is a two element vector, it represents the minimum and maximum values of both X and Y, or T for a parametric plot.  If DOM is a four element vector, then the minimum and maximum values are [xmin xmax ymin ymax].

     N is a scalar defining the number of points to use in plotting the function.

     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 vector of graphics handles to the created line objects.

     plot, ezplot3, ezpolar, ezcontour, ezcontourf, ezmesh, ezmeshc, ezsurf, ezsurfc

 -- ezcontour: (F)
 -- ezcontour: (..., DOM)
 -- ezcontour: (..., N)
 -- ezcontour: (HAX, ...)
 -- H =: ezcontour (...)

     Plot the contour lines of a function.

     F is a string, inline function, or function handle with two arguments defining the function.  By default the plot is over the meshed domain -2*pi <= X | Y <= 2*pi with 60 points in each dimension.

     If DOM is a two element vector, it represents the minimum and maximum values of both X and Y.  If DOM is a four element vector, then the minimum and maximum values are [xmin xmax ymin ymax].

     N is a scalar defining the number of points to use in each dimension.

     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 plot.

     Example:

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezcontour (f, [-3, 3]);

     contour, ezcontourf, ezplot, ezmeshc, ezsurfc

 -- ezcontourf: (F)
 -- ezcontourf: (..., DOM)
 -- ezcontourf: (..., N)
 -- ezcontourf: (HAX, ...)
 -- H =: ezcontourf (...)

     Plot the filled contour lines of a function.

     F is a string, inline function, or function handle with two arguments defining the function.  By default the plot is over the meshed domain -2*pi <= X | Y <= 2*pi with 60 points in each dimension.

     If DOM is a two element vector, it represents the minimum and maximum values of both X and Y.  If DOM is a four element vector, then the minimum and maximum values are [xmin xmax ymin ymax].

     N is a scalar defining the number of points to use in each dimension.

     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 plot.

     Example:

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezcontourf (f, [-3, 3]);

     contourf, ezcontour, ezplot, ezmeshc, ezsurfc

 -- ezpolar: (F)
 -- ezpolar: (..., DOM)
 -- ezpolar: (..., N)
 -- ezpolar: (HAX, ...)
 -- H =: ezpolar (...)

     Plot a 2-D function in polar coordinates.

     The function F is a string, inline function, or function handle with a single argument.  The expected form of the function is RHO = F(THETA). By default the plot is over the domain 0 <= THETA <= 2*pi with 500 points.

     If DOM is a two element vector, it represents the minimum and maximum values of THETA.

     N is a scalar defining the number of points to use in plotting the function.

     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 plot.

     Example:

          ezpolar (@(t) sin (5/4 * t), [0, 8*pi]);

     polar, ezplot

Two-dimensional Geometric Shapes
................................

 -- rectangle: ()
 -- rectangle: (..., "Position", POS)
 -- rectangle: (..., "Curvature", CURV)
 -- rectangle: (..., "EdgeColor", EC)
 -- rectangle: (..., "FaceColor", FC)
 -- rectangle: (HAX, ...)
 -- H =: rectangle (...)
     Draw a rectangular patch defined by POS and CURV.

     The variable POS(1:2) defines the lower left-hand corner of the patch and POS(3:4) defines its width and height.  By default, the value of POS is [0, 0, 1, 1].

     The variable CURV defines the curvature of the sides of the rectangle and may be a scalar or two-element vector with values between 0 and 1. A value of 0 represents no curvature of the side, whereas a value of 1 means that the side is entirely curved into the arc of a circle. If CURV is a two-element vector, then the first element is the curvature along the x-axis of the patch and the second along y-axis.

     If CURV is a scalar, it represents the curvature of the shorter of the two sides of the rectangle and the curvature of the other side is defined by

          min (pos(1:2)) / max (pos(1:2)) * curv

     Additional property/value pairs are passed to the underlying patch command.

     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 rectangle object. patch, line, cylinder, ellipsoid, sphere

Three-Dimensional Plots
-----------------------

The function mesh produces mesh surface plots.  For example,

     tx = ty = linspace (-8, 8, 41)';
     [xx, yy] = meshgrid (tx, ty);
     r = sqrt (xx .^ 2 + yy .^ 2) + eps;
     tz = sin (r) ./ r;
     mesh (tx, ty, tz);
     xlabel ("tx");
     ylabel ("ty");
     zlabel ("tz");
     title ("3-D Sombrero plot");

produces the familiar ``sombrero'' plot shown in fig:mesh.  Note the use of the function meshgrid to create matrices of X and Y coordinates to use for plotting the Z data.  The ndgrid function is similar to meshgrid, but works for N-dimensional matrices.

Figure: Mesh plot.

The meshc function is similar to mesh, but also produces a plot of contours for the surface.

The plot3 function displays arbitrary three-dimensional data, without requiring it to form a surface.  For example,

     t = 0:0.1:10*pi;
     r = linspace (0, 1, numel (t));
     z = linspace (0, 1, numel (t));
     plot3 (r.*sin (t), r.*cos (t), z);
     xlabel ("r.*sin (t)");
     ylabel ("r.*cos (t)");
     zlabel ("z");
     title ("plot3 display of 3-D helix");

displays the spiral in three dimensions shown in fig:plot3.

Figure: Three-dimensional spiral.

Finally, the view function changes the viewpoint for three-dimensional plots.

 -- mesh: (X, Y, Z)
 -- mesh: (Z)
 -- mesh: (..., C)
 -- mesh: (..., PROP, VAL, ...)
 -- mesh: (HAX, ...)
 -- H =: mesh (...)
     Plot a 3-D wireframe mesh.

     The wireframe mesh is plotted using rectangles.  The vertices of the rectangles [X, Y] are typically the output of meshgrid. over a 2-D rectangular region in the x-y plane.  Z determines the height above the plane of each vertex.  If only a single Z matrix is given, then it is plotted over the meshgrid X = 1:columns (Z), Y = 1:rows (Z). Thus, columns of Z correspond to different X values and rows of Z correspond to different Y values.

     The color of the mesh is computed by linearly scaling the Z values to fit the range of the current colormap.  Use caxis and/or change the colormap to control the appearance.

     Optionally, the color of the mesh can be specified independently of Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying 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.

     ezmesh, meshc, meshz, trimesh, contour, surf, surface, meshgrid, hidden, shading, colormap, caxis

 -- meshc: (X, Y, Z)
 -- meshc: (Z)
 -- meshc: (..., C)
 -- meshc: (..., PROP, VAL, ...)
 -- meshc: (HAX, ...)
 -- H =: meshc (...)
     Plot a 3-D wireframe mesh with underlying contour lines.

     The wireframe mesh is plotted using rectangles.  The vertices of the rectangles [X, Y] are typically the output of meshgrid. over a 2-D rectangular region in the x-y plane.  Z determines the height above the plane of each vertex.  If only a single Z matrix is given, then it is plotted over the meshgrid X = 1:columns (Z), Y = 1:rows (Z). Thus, columns of Z correspond to different X values and rows of Z correspond to different Y values.

     The color of the mesh is computed by linearly scaling the Z values to fit the range of the current colormap.  Use caxis and/or change the colormap to control the appearance.

     Optionally the color of the mesh can be specified independently of Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying 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 2-element vector with a graphics handle to the created surface object and to the created contour plot.

     ezmeshc, mesh, meshz, contour, surfc, surface, meshgrid, hidden, shading, colormap, caxis

 -- meshz: (X, Y, Z)
 -- meshz: (Z)
 -- meshz: (..., C)
 -- meshz: (..., PROP, VAL, ...)
 -- meshz: (HAX, ...)
 -- H =: meshz (...)
     Plot a 3-D wireframe mesh with a surrounding curtain.

     The wireframe mesh is plotted using rectangles.  The vertices of the rectangles [X, Y] are typically the output of meshgrid. over a 2-D rectangular region in the x-y plane.  Z determines the height above the plane of each vertex.  If only a single Z matrix is given, then it is plotted over the meshgrid X = 1:columns (Z), Y = 1:rows (Z). Thus, columns of Z correspond to different X values and rows of Z correspond to different Y values.

     The color of the mesh is computed by linearly scaling the Z values to fit the range of the current colormap.  Use caxis and/or change the colormap to control the appearance.

     Optionally the color of the mesh can be specified independently of Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying 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.

     mesh, meshc, contour, surf, surface, waterfall, meshgrid, hidden, shading, colormap, caxis

 -- hidden:
 -- hidden: on
 -- hidden: off
 -- MODE =: hidden (...)
     Control mesh hidden line removal.

     When called with no argument the hidden line removal state is toggled.

     When called with one of the modes "on" or "off" the state is set accordingly.

     The optional output argument MODE is the current state.

     Hidden Line Removal determines what graphic objects behind a mesh plot are visible.  The default is for the mesh to be opaque and lines behind the mesh are not visible.  If hidden line removal is turned off then objects behind the mesh can be seen through the faces (openings) of the mesh, although the mesh grid lines are still opaque.

     mesh, meshc, meshz, ezmesh, ezmeshc, trimesh, waterfall

 -- surf: (X, Y, Z)
 -- surf: (Z)
 -- surf: (..., C)
 -- surf: (..., PROP, VAL, ...)
 -- surf: (HAX, ...)
 -- H =: surf (...)
     Plot a 3-D surface mesh.

     The surface mesh is plotted using shaded rectangles.  The vertices of the rectangles [X, Y] are typically the output of meshgrid. over a 2-D rectangular region in the x-y plane.  Z determines the height above the plane of each vertex.  If only a single Z matrix is given, then it is plotted over the meshgrid X = 1:columns (Z), Y = 1:rows (Z). Thus, columns of Z correspond to different X values and rows of Z correspond to different Y values.

     The color of the surface is computed by linearly scaling the Z values to fit the range of the current colormap.  Use caxis and/or change the colormap to control the appearance.

     Optionally, the color of the surface can be specified independently of Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying 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.

     Note: The exact appearance of the surface can be controlled with the shading command or by using set to control surface object properties. ezsurf, surfc, surfl, surfnorm, trisurf, contour, mesh, surface, meshgrid, hidden, shading, colormap, caxis

 -- surfc: (X, Y, Z)
 -- surfc: (Z)
 -- surfc: (..., C)
 -- surfc: (..., PROP, VAL, ...)
 -- surfc: (HAX, ...)
 -- H =: surfc (...)
     Plot a 3-D surface mesh with underlying contour lines.

     The surface mesh is plotted using shaded rectangles.  The vertices of the rectangles [X, Y] are typically the output of meshgrid. over a 2-D rectangular region in the x-y plane.  Z determines the height above the plane of each vertex.  If only a single Z matrix is given, then it is plotted over the meshgrid X = 1:columns (Z), Y = 1:rows (Z). Thus, columns of Z correspond to different X values and rows of Z correspond to different Y values.

     The color of the surface is computed by linearly scaling the Z values to fit the range of the current colormap.  Use caxis and/or change the colormap to control the appearance.

     Optionally, the color of the surface can be specified independently of Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying 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.

     Note: The exact appearance of the surface can be controlled with the shading command or by using set to control surface object properties. ezsurfc, surf, surfl, surfnorm, trisurf, contour, mesh, surface, meshgrid, hidden, shading, colormap, caxis

 -- surfl: (Z)
 -- surfl: (X, Y, Z)
 -- surfl: (..., LSRC)
 -- surfl: (X, Y, Z, LSRC, P)
 -- surfl: (..., "cdata")
 -- surfl: (..., "light")
 -- surfl: (HAX, ...)
 -- H =: surfl (...)
     Plot a 3-D surface using shading based on various lighting models.

     The surface mesh is plotted using shaded rectangles.  The vertices of the rectangles [X, Y] are typically the output of meshgrid. over a 2-D rectangular region in the x-y plane.  Z determines the height above the plane of each vertex.  If only a single Z matrix is given, then it is plotted over the meshgrid X = 1:columns (Z), Y = 1:rows (Z). Thus, columns of Z correspond to different X values and rows of Z correspond to different Y values.

     The default lighting mode "cdata", changes the cdata property of the surface object to give the impression of a lighted surface. Warning: The alternative mode "light" mode which creates a light object to illuminate the surface is not implemented (yet).

     The light source location can be specified using LSRC.  It can be given as a 2-element vector [azimuth, elevation] in degrees, or as a 3-element vector [lx, ly, lz].  The default value is rotated 45 degrees counterclockwise to the current view.

     The material properties of the surface can specified using a 4-element vector P = [AM D SP EXP] which defaults to P = [0.55 0.6 0.4 10].

     "AM" strength of ambient light

     "D" strength of diffuse reflection

     "SP" strength of specular reflection

     "EXP" specular exponent

     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.

     Example:

          colormap (bone (64));
          surfl (peaks);
          shading interp;

     diffuse, specular, surf, shading, colormap, caxis

 -- surfnorm: (X, Y, Z)
 -- surfnorm: (Z)
 -- surfnorm: (..., PROP, VAL, ...)
 -- surfnorm: (HAX, ...)
 -- [NX, NY, NZ] =: surfnorm (...)
     Find the vectors normal to a meshgridded 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).

     If no return arguments are requested, a surface plot with the normal vectors to the surface is plotted.

     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.

     If output arguments are requested then the components of the normal vectors are returned in NX, NY, and NZ and no plot is made.  The normal vectors are unnormalized (magnitude != 1).  To normalize, use

          len = sqrt (nx.^2 + ny.^2 + nz.^2);
          nx ./= len;  ny ./= len;  nz ./= len;

     An example of the use of surfnorm is

          surfnorm (peaks (25));

     Algorithm: The normal vectors are calculated by taking the cross product of the diagonals of each of the quadrilateral faces in the meshgrid to find the normal vectors at the center of each face.  Next, for each meshgrid point the four nearest normal vectors are averaged to obtain the final normal to the surface at the meshgrid point.

     For surface objects, the "VertexNormals" property contains equivalent information, except possibly near the boundary of the surface where different interpolation schemes may yield slightly different values.

     isonormals, quiver3, surf, meshgrid

 -- FV =: isosurface (V, ISOVAL)
 -- FV =: isosurface (V)
 -- FV =: isosurface (X, Y, Z, V, ISOVAL)
 -- FV =: isosurface (X, Y, Z, V)
 -- FVC =: isosurface (..., COL)
 -- FV =: isosurface (..., "noshare")
 -- FV =: isosurface (..., "verbose")
 -- [F, V] =: isosurface (...)
 -- [F, V, C] =: isosurface (...)
 -- isosurface: (...)

     Calculate isosurface of 3-D volume data.

     An isosurface connects points with the same value and is analogous to a contour plot, but in three dimensions.

     The input argument V is a three-dimensional array that contains data sampled over a volume.

     The input ISOVAL is a scalar that specifies the value for the isosurface.  If ISOVAL is omitted or empty, a "good" value for an isosurface is determined from V.

     When called with a single output argument isosurface returns a structure array FV that contains the fields FACES and VERTICES computed at the points [X, Y, Z] = meshgrid (1:l, 1:m, 1:n) where [l, m, n] = size (V).  The output FV can be used directly as input to the patch function.

     If called with additional input arguments X, Y, and Z that are three-dimensional arrays with the same size as V or vectors with lengths corresponding to the dimensions of V, then the volume data is taken at the specified points.  If X, Y, or Z are empty, the grid corresponds to the indices (1:n) in the respective direction (see meshgrid).

     The optional input argument COL, which is a three-dimensional array of the same size as V, specifies coloring of the isosurface.  The color data is interpolated, as necessary, to match ISOVAL.  The output structure array, in this case, has the additional field FACEVERTEXCDATA.

     If given the string input argument "noshare", vertices may be returned multiple times for different faces.  The default behavior is to eliminate vertices shared by adjacent faces with unique which may be time consuming.

     The string input argument "verbose" is supported for MATLAB compatibility, but has no effect.

     Any string arguments must be passed after the other arguments.

     If called with two or three output arguments, return the information about the faces F, vertices V, and color data C as separate arrays instead of a single structure array.

     If called with no output argument, the isosurface geometry is directly plotted with the patch command and a light object is added to the axes if not yet present.

     For example,

          [x, y, z] = meshgrid (1:5, 1:5, 1:5);
          v = rand (5, 5, 5);
          isosurface (x, y, z, v, .5);

     will directly draw a random isosurface geometry in a graphics window.

     An example of an isosurface geometry with different additional coloring:

          N = 15;    # Increase number of vertices in each direction
          iso = .4;  # Change isovalue to .1 to display a sphere
          lin = linspace (0, 2, N);
          [x, y, z] = meshgrid (lin, lin, lin);
          v = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2);
          figure ();

          subplot (2,2,1); view (-38, 20);
          [f, vert] = isosurface (x, y, z, v, iso);
          p = patch ("Faces", f, "Vertices", vert, "EdgeColor", "none");
          pbaspect ([1 1 1]);
          isonormals (x, y, z, v, p)
          set (p, "FaceColor", "green", "FaceLighting", "gouraud");
          light ("Position", [1 1 5]);

          subplot (2,2,2); view (-38, 20);
          p = patch ("Faces", f, "Vertices", vert, "EdgeColor", "blue");
          pbaspect ([1 1 1]);
          isonormals (x, y, z, v, p)
          set (p, "FaceColor", "none", "EdgeLighting", "gouraud");
          light ("Position", [1 1 5]);

          subplot (2,2,3); view (-38, 20);
          [f, vert, c] = isosurface (x, y, z, v, iso, y);
          p = patch ("Faces", f, "Vertices", vert, "FaceVertexCData", c, ...
                     "FaceColor", "interp", "EdgeColor", "none");
          pbaspect ([1 1 1]);
          isonormals (x, y, z, v, p)
          set (p, "FaceLighting", "gouraud");
          light ("Position", [1 1 5]);

          subplot (2,2,4); view (-38, 20);
          p = patch ("Faces", f, "Vertices", vert, "FaceVertexCData", c, ...
                     "FaceColor", "interp", "EdgeColor", "blue");
          pbaspect ([1 1 1]);
          isonormals (x, y, z, v, p)
          set (p, "FaceLighting", "gouraud");
          light ("Position", [1 1 5]);

     isonormals, isocolors, isocaps, smooth3, reducevolume, reducepatch, patch

 -- VN =: isonormals (VAL, VERT)
 -- VN =: isonormals (VAL, HP)
 -- VN =: isonormals (X, Y, Z, VAL, VERT)
 -- VN =: isonormals (X, Y, Z, VAL, HP)
 -- VN =: isonormals (..., "negate")
 -- isonormals: (VAL, HP)
 -- isonormals: (X, Y, Z, VAL, HP)
 -- isonormals: (..., "negate")

     Calculate normals to an isosurface.

     The vertex normals VN are calculated from the gradient of the 3-dimensional array VAL (size: lxmxn) containing the data for an isosurface geometry.  The normals point towards smaller values in VAL.

     If called with one output argument VN, and the second input argument VERT holds the vertices of an isosurface, then the normals VN are calculated at the vertices VERT on a grid given by [x, y, z] = meshgrid (1:l, 1:m, 1:n).  The output argument VN has the same size as VERT and can be used to set the "VertexNormals" property of the corresponding patch.

     If called with additional input arguments X, Y, and Z, which are 3-dimensional arrays with the same size as VAL, then the volume data is taken at these points.  Instead of the vertex data VERT, a patch handle HP can be passed to the function.

     If the last input argument is the string "negate", compute the reverse vector normals of an isosurface geometry (i.e., pointed towards larger values in VAL).

     If no output argument is given, the property "VertexNormals" of the patch associated with the patch handle HP is changed directly.

     isosurface, isocolors, smooth3

 -- FVC =: isocaps (V, ISOVAL)
 -- FVC =: isocaps (V)
 -- FVC =: isocaps (X, Y, Z, V, ISOVAL)
 -- FVC =: isocaps (X, Y, Z, V)
 -- FVC =: isocaps (..., WHICH_CAPS)
 -- FVC =: isocaps (..., WHICH_PLANE)
 -- FVC =: isocaps (..., "verbose")
 -- [FACES, VERTICES, FVCDATA] =: isocaps (...)
 -- isocaps: (...)

     Create end-caps for isosurfaces of 3-D data.

     This function places caps at the open ends of isosurfaces.

     The input argument V is a three-dimensional array that contains data sampled over a volume.

     The input ISOVAL is a scalar that specifies the value for the isosurface.  If ISOVAL is omitted or empty, a "good" value for an isosurface is determined from V.

     When called with a single output argument, isocaps returns a structure array FVC with the fields: faces, vertices, and facevertexcdata.  The results are computed at the points [X, Y, Z] = meshgrid (1:l, 1:m, 1:n) where [l, m, n] = size (V).  The output FVC can be used directly as input to the patch function.

     If called with additional input arguments X, Y, and Z that are three-dimensional arrays with the same size as V or vectors with lengths corresponding to the dimensions of V, then the volume data is taken at the specified points.  If X, Y, or Z are empty, the grid corresponds to the indices (1:n) in the respective direction (see meshgrid).

     The optional parameter WHICH_CAPS can have one of the following string values which defines how the data will be enclosed:

     "above", "a" (default)
          for end-caps that enclose the data above ISOVAL.

     "below", "b"
          for end-caps that enclose the data below ISOVAL.

     The optional parameter WHICH_PLANE can have one of the following string values to define which end-cap should be drawn:

     "all" (default)
          for all of the end-caps.

     "xmin"
          for end-caps at the lower x-plane of the data.

     "xmax"
          for end-caps at the upper x-plane of the data.

     "ymin"
          for end-caps at the lower y-plane of the data.

     "ymax"
          for end-caps at the upper y-plane of the data.

     "zmin"
          for end-caps at the lower z-plane of the data.

     "zmax"
          for end-caps at the upper z-plane of the data.

     The string input argument "verbose" is supported for MATLAB compatibility, but has no effect.

     If called with two or three output arguments, the data for faces FACES, vertices VERTICES, and the color data FACEVERTEXCDATA are returned in separate arrays instead of a single structure.

     If called with no output argument, the end-caps are drawn directly in the current figure with the patch command.

     isosurface, isonormals, patch

 -- CDAT =: isocolors (C, V)
 -- CDAT =: isocolors (X, Y, Z, C, V)
 -- CDAT =: isocolors (X, Y, Z, R, G, B, V)
 -- CDAT =: isocolors (R, G, B, V)
 -- CDAT =: isocolors (..., P)
 -- isocolors: (...)

     Compute isosurface colors.

     If called with one output argument, and the first input argument C is a three-dimensional array that contains indexed color values, and the second input argument V are the vertices of an isosurface geometry, then return a matrix CDAT with color data information for the geometry at computed points [x, y, z] = meshgrid (1:l, 1:m, 1:n).  The output argument CDAT can be used to manually set the "FaceVertexCData" property of an isosurface patch object.

     If called with additional input arguments X, Y and Z which are three-dimensional arrays of the same size as C then the color data is taken at those specified points.

     Instead of indexed color data C, isocolors can also be called with RGB values R, G, B.  If input arguments X, Y, Z are not given then meshgrid computed values are used.

     Optionally, a patch handle P can be given as the last input argument to all function call variations and the vertex data will be extracted from the isosurface patch object.  Finally, if no output argument is given then the colors of the patch given by the patch handle P are changed.

     isosurface, isonormals

 -- SMOOTHED_DATA =: smooth3 (DATA)
 -- SMOOTHED_DATA =: smooth3 (DATA, METHOD)
 -- SMOOTHED_DATA =: smooth3 (DATA, METHOD, SZ)
 -- SMOOTHED_DATA =: smooth3 (DATA, METHOD, SZ, STD_DEV)
     Smooth values of 3-dimensional matrix DATA.

     This function can be used, for example, to reduce the impact of noise in DATA before calculating isosurfaces.

     DATA must be a non-singleton 3-dimensional matrix.  The smoothed data from this matrix is returned in SMOOTHED_DATA which is of the same size as DATA.

     The option input METHOD determines which convolution kernel is used for the smoothing process.  Possible choices:

     "box", "b" (default)
          to use a convolution kernel with sharp edges.

     "gaussian", "g"
          to use a convolution kernel that is represented by a non-correlated trivariate normal distribution function.

     SZ is either a vector of 3 elements representing the size of the convolution kernel in x-, y- and z-direction or a scalar, in which case the same size is used in all three dimensions.  The default value is 3.

     When METHOD is "gaussian", STD_DEV defines the standard deviation of the trivariate normal distribution function.  STD_DEV is either a vector of 3 elements representing the standard deviation of the Gaussian convolution kernel in x-, y- and z-directions or a scalar, in which case the same value is used in all three dimensions.  The default value is 0.65.

     isosurface, isonormals, patch

 -- [NX, NY, NZ, NV] =: reducevolume (V, R)
 -- [NX, NY, NZ, NV] =: reducevolume (X, Y, Z, V, R)
 -- NV =: reducevolume (...)

     Reduce the volume of the dataset in V according to the values in R.

     V is a matrix that is non-singleton in the first 3 dimensions.

     R can either be a vector of 3 elements representing the reduction factors in the x-, y-, and z-directions or a scalar, in which case the same reduction factor is used in all three dimensions.

     reducevolume reduces the number of elements of V by taking only every R-th element in the respective dimension.

     Optionally, X, Y, and Z can be supplied to represent the set of coordinates of V.  They can either be matrices of the same size as V or vectors with sizes according to the dimensions of V, in which case they are expanded to matrices (see meshgrid).

     If reducevolume is called with two arguments then X, Y, and Z are assumed to match the respective indices of V.

     The reduced matrix is returned in NV.

     Optionally, the reduced set of coordinates are returned in NX, NY, and NZ, respectively.

     Examples:

          V = reshape (1:6*8*4, [6 8 4]);
          NV = reducevolume (V, [4 3 2]);

          V = reshape (1:6*8*4, [6 8 4]);
          X = 1:3:24;  Y = -14:5:11;  Z = linspace (16, 18, 4);
          [NX, NY, NZ, NV] = reducevolume (X, Y, Z, V, [4 3 2]);

     isosurface, isonormals

 -- REDUCED_FV =: reducepatch (FV)
 -- REDUCED_FV =: reducepatch (FACES, VERTICES)
 -- REDUCED_FV =: reducepatch (PATCH_HANDLE)
 -- reducepatch: (PATCH_HANDLE)
 -- REDUCED_FV =: reducepatch (..., REDUCTION_FACTOR)
 -- REDUCED_FV =: reducepatch (..., "fast")
 -- REDUCED_FV =: reducepatch (..., "verbose")
 -- [REDUCED_FACES, REDUCES_VERTICES] =: reducepatch (...)

     Reduce the number of faces and vertices in a patch object while retaining the overall shape of the patch.

     The input patch can be represented by a structure FV with the fields faces and vertices, by two matrices FACES and VERTICES (see, e.g., the result of isosurface), or by a handle to a patch object PATCH_HANDLE (see patch).

     The number of faces and vertices in the patch is reduced by iteratively collapsing the shortest edge of the patch to its midpoint (as discussed, e.g., here: https://libigl.github.io/libigl/tutorial/tutorial.html#meshdecimation).

     Currently, only patches consisting of triangles are supported.  The resulting patch also consists only of triangles.

     If reducepatch is called with a handle to a valid patch PATCH_HANDLE, and without any output arguments, then the given patch is updated immediately.

     If the REDUCTION_FACTOR is omitted, the resulting structure REDUCED_FV includes approximately 50% of the faces of the original patch.  If REDUCTION_FACTOR is a fraction between 0 (excluded) and 1 (excluded), a patch with approximately the corresponding fraction of faces is determined. If REDUCTION_FACTOR is an integer greater than or equal to 1, the resulting patch has approximately REDUCTION_FACTOR faces.  Depending on the geometry of the patch, the resulting number of faces can differ from the given value of REDUCTION_FACTOR.  This is especially true when many shared vertices are detected.

     For the reduction, it is necessary that vertices of touching faces are shared.  Shared vertices are detected automatically.  This detection can be skipped by passing the optional string argument "fast".

     With the optional string arguments "verbose", additional status messages are printed to the command window.

     Any string input arguments must be passed after all other arguments.

     If called with one output argument, the reduced faces and vertices are returned in a structure REDUCED_FV with the fields faces and vertices (see the one output option of isosurface).

     If called with two output arguments, the reduced faces and vertices are returned in two separate matrices REDUCED_FACES and REDUCED_VERTICES.

     isosurface, isonormals, reducevolume, patch

 -- shrinkfaces: (P, SF)
 -- NFV =: shrinkfaces (P, SF)
 -- NFV =: shrinkfaces (FV, SF)
 -- NFV =: shrinkfaces (F, V, SF)
 -- [NF, NV] =: shrinkfaces (...)

     Reduce the size of faces in a patch by the shrink factor SF.

     The patch object can be specified by a graphics handle (P), a patch structure (FV) with the fields "faces" and "vertices", or as two separate matrices (F, V) of faces and vertices.

     The shrink factor SF is a positive number specifying the percentage of the original area the new face will occupy.  If no factor is given the default is 0.3 (a reduction to 30% of the original size).  A factor greater than 1.0 will result in the expansion of faces.

     Given a patch handle as the first input argument and no output parameters, perform the shrinking of the patch faces in place and redraw the patch.

     If called with one output argument, return a structure with fields "faces", "vertices", and "facevertexcdata" containing the data after shrinking.  This structure can be used directly as an input argument to the patch function.

     Caution:: Performing the shrink operation on faces which are not convex can lead to undesirable results.

     Example: a triangulated 3/4 circle and the corresponding shrunken version.

          [phi r] = meshgrid (linspace (0, 1.5*pi, 16), linspace (1, 2, 4));
          tri = delaunay (phi(:), r(:));
          v = [r(:).*sin(phi(:)) r(:).*cos(phi(:))];
          clf ()
          p = patch ("Faces", tri, "Vertices", v, "FaceColor", "none");
          fv = shrinkfaces (p);
          patch (fv)
          axis equal
          grid on

     patch

 -- diffuse: (SX, SY, SZ, LV)
     Calculate the diffuse reflection strength of a surface defined by the normal vector elements SX, SY, SZ.

     The light source location vector LV can be given as a 2-element vector [azimuth, elevation] in degrees or as a 3-element vector [x, y, z]. specular, surfl

 -- specular: (SX, SY, SZ, LV, VV)
 -- specular: (SX, SY, SZ, LV, VV, SE)
     Calculate the specular reflection strength of a surface defined by the normal vector elements SX, SY, SZ using Phong's approximation.

     The light source location and viewer location vectors are specified using parameters LV and VV respectively.  The location vectors can given as 2-element vectors [azimuth, elevation] in degrees or as 3-element vectors [x, y, z].

     An optional sixth argument specifies the specular exponent (spread) SE.  If not given, SE defaults to 10. diffuse, surfl

 -- lighting: (TYPE)
 -- lighting: (HAX, TYPE)
     Set the lighting of patch or surface graphic objects.

     Valid arguments for TYPE are

     "flat"
          Draw objects with faceted lighting effects.

     "gouraud"
          Draw objects with linear interpolation of the lighting effects between the vertices.

     "none"
          Draw objects without light and shadow effects.

     If the first argument HAX is an axes handle, then change the lighting effects of objects in this axes, rather than the current axes returned by gca.

     The lighting effects are only visible if at least one light object is present and visible in the same axes.

     light, fill, mesh, patch, pcolor, surf, surface, shading

 -- material: shiny
 -- material: dull
 -- material: metal
 -- material: default
 -- material: ([AS, DS, SS])
 -- material: ([AS, DS, SS, SE])
 -- material: ([AS, DS, SS, SE, SCR])
 -- material: (HLIST, ...)
 -- MTYPES =: material ()
 -- REFL_PROPS =: material (MTYPE_STRING)
     Set reflectance properties for the lighting of surfaces and patches.

     This function changes the ambient, diffuse, and specular strengths, as well as the specular exponent and specular color reflectance, of all patch and surface objects in the current axes.  This can be used to simulate, to some extent, the reflectance properties of certain materials when used with light.

     When called with a string, the aforementioned properties are set according to the values in the following table:

       MTYPE   ambient- strength   diffuse-
     strength   specular- strength   specular- exponent   specular-
     color- reflectance
       "shiny"   0.3   0.6   0.9   20   1.0
       "dull"   0.3   0.8   0.0   10   1.0
       "metal"   0.3   0.3   1.0   25   0.5
       "default"   "default"   "default"   "default"
     "default"   "default"

     When called with a vector of three elements, the ambient, diffuse, and specular strengths of all patch and surface objects in the current axes are updated.  An optional fourth vector element updates the specular exponent, and an optional fifth vector element updates the specular color reflectance.

     A list of graphic handles can also be passed as the first argument.  In this case, the properties of these handles and all child patch and surface objects will be updated.

     Additionally, material can be called with a single output argument. If called without input arguments, a column cell vector MTYPES with the strings for all available materials is returned.  If the one input argument MTYPE_STRING is the name of a material, a 1x5 cell vector REFL_PROPS with the reflectance properties of that material is returned.  In both cases, no graphic properties are changed.

     light, fill, mesh, patch, pcolor, surf, surface

 -- camlight:
 -- camlight: right
 -- camlight: left
 -- camlight: headlight
 -- camlight: (AZ, EL)
 -- camlight: (..., STYLE)
 -- camlight: (HL, ...)
 -- H =: camlight (...)
     Add a light object to a figure using a simple interface.

     When called with no arguments, a light object is added to the current plot and is placed slightly above and to the right of the camera's current position: this is equivalent to camlight right.  The commands camlight left and camlight headlight behave similarly with the placement being either left of the camera position or centered on the camera position.

     For more control, the light position can be specified by an azimuthal rotation AZ and an elevation angle EL, both in degrees, relative to the current properties of the camera.

     The optional string STYLE specifies whether the light is a local point source ("local", the default) or placed at infinite distance ("infinite").

     If the first argument HL is a handle to a light object, then act on this light object rather than creating a new object.

     The optional return value H is a graphics handle to the light object. This can be used to move or further change properties of the light object.

     Examples:

     Add a light object to a plot

          sphere (36);
          camlight

     Position the light source exactly

          camlight (45, 30);

     Here the light is first pitched upwards (see camup) from the camera position (see campos) by 30 degrees.  It is then yawed by 45 degrees to the right.  Both rotations are centered around the camera target (see camtarget).

     Return a handle to further manipulate the light object

          clf
          sphere (36);
          hl = camlight ("left");
          set (hl, "color", "r");

     light

 -- [XX, YY] =: meshgrid (X, Y)
 -- [XX, YY, ZZ] =: meshgrid (X, Y, Z)
 -- [XX, YY] =: meshgrid (X)
 -- [XX, YY, ZZ] =: meshgrid (X)
     Given vectors of X and Y coordinates, return matrices XX and YY corresponding to a full 2-D grid.

     The rows of XX are copies of X, and the columns of YY are copies of Y.  If Y is omitted, then it is assumed to be the same as X.

     If the optional Z input is given, or ZZ is requested, then the output will be a full 3-D grid.  If Z is omitted and ZZ is requested, it is assumed to be the same as Y.

     meshgrid is most frequently used to produce input for a 2-D or 3-D function that will be plotted.  The following example creates a surface plot of the ``sombrero'' function.

          f = @(x,y) sin (sqrt (x.^2 + y.^2)) ./ sqrt (x.^2 + y.^2);
          range = linspace (-8, 8, 41);
          [X, Y] = meshgrid (range, range);
          Z = f (X, Y);
          surf (X, Y, Z);

     Programming Note: meshgrid is restricted to 2-D or 3-D grid generation.  The ndgrid function will generate 1-D through N-D grids.  However, the functions are not completely equivalent.  If X is a vector of length M and Y is a vector of length N, then meshgrid will produce an output grid which is NxM.  ndgrid will produce an output which is MxN (transpose) for the same input.  Some core functions expect meshgrid input and others expect ndgrid input.  Check the documentation for the function in question to determine the proper input format. ndgrid, mesh, contour, surf

 -- [Y1, Y2, ..., Yn] =: ndgrid (X1, X2, ..., Xn)
 -- [Y1, Y2, ..., Yn] =: ndgrid (X)
     Given n vectors X1, ..., Xn, ndgrid returns n arrays of dimension n.

     The elements of the i-th output argument contains the elements of the vector Xi repeated over all dimensions different from the i-th dimension.  Calling ndgrid with only one input argument X is equivalent to calling ndgrid with all n input arguments equal to X:

     [Y1, Y2, ..., Yn] = ndgrid (X, ..., X)

     Programming Note: ndgrid is very similar to the function meshgrid except that the first two dimensions are transposed in comparison to meshgrid.  Some core functions expect meshgrid input and others expect ndgrid input.  Check the documentation for the function in question to determine the proper input format. meshgrid

 -- plot3: (X, Y, Z)
 -- plot3: (X, Y, Z, PROP, VALUE, ...)
 -- plot3: (X, Y, Z, FMT)
 -- plot3: (X, CPLX)
 -- plot3: (CPLX)
 -- plot3: (HAX, ...)
 -- H =: plot3 (...)
     Produce 3-D plots.

     Many different combinations of arguments are possible.  The simplest form is

          plot3 (X, Y, Z)

     in which the arguments are taken to be the vertices of the points to be plotted in three dimensions.  If all arguments are vectors of the same length, then a single continuous line is drawn.  If all arguments are matrices, then each column of is treated as a separate line.  No attempt is made to transpose the arguments to make the number of rows match.

     If only two arguments are given, as

          plot3 (X, CPLX)

     the real and imaginary parts of the second argument are used as the Y and Z coordinates, respectively.

     If only one argument is given, as

          plot3 (CPLX)

     the real and imaginary parts of the argument are used as the Y and Z values, and they are plotted versus their index.

     Arguments may also be given in groups of three as

          plot3 (X1, Y1, Z1, X2, Y2, Z2, ...)

     in which each set of three arguments is treated as a separate line or set of lines in three dimensions.

     To plot multiple one- or two-argument groups, separate each group with an empty format string, as

          plot3 (X1, C1, "", C2, "", ...)

     Multiple property-value pairs may be specified which will affect the line objects drawn by plot3.  If the FMT argument is supplied it will format the line objects in the same manner as plot.

     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 plot.

     Example:

          z = [0:0.05:5];
          plot3 (cos (2*pi*z), sin (2*pi*z), z, ";helix;");
          plot3 (z, exp (2i*pi*z), ";complex sinusoid;");

     ezplot3, plot

 -- view: (AZIMUTH, ELEVATION)
 -- view: ([AZIMUTH ELEVATION])
 -- view: ([X Y Z])
 -- view: (2)
 -- view: (3)
 -- view: (HAX, ...)
 -- [AZIMUTH, ELEVATION] =: view ()
     Query or set the viewpoint for the current axes.

     The parameters AZIMUTH and ELEVATION can be given as two arguments or as 2-element vector.  The viewpoint can also be specified with Cartesian coordinates X, Y, and Z.

     The call view (2) sets the viewpoint to AZIMUTH = 0 and ELEVATION = 90, which is the default for 2-D graphs.

     The call view (3) sets the viewpoint to AZIMUTH = -37.5 and ELEVATION = 30, which is the default for 3-D graphs.

     If the first argument HAX is an axes handle, then operate on this axes rather than the current axes returned by gca.

     If no inputs are given, return the current AZIMUTH and ELEVATION.

 -- camlookat: ()
 -- camlookat: (H)
 -- camlookat: (HANDLE_LIST)
 -- camlookat: (HAX)
     Move the camera and adjust its properties to look at objects.

     When the input is a handle H, the camera is set to point toward the center of the bounding box of H.  The camera's position is adjusted so the bounding box approximately fills the field of view.

     This command fixes the camera's viewing direction (camtarget() - campos()), camera up vector (see camup) and viewing angle (see camva).  The camera target (see camtarget) and camera position (see campos) are changed.

     If the argument is a list HANDLE_LIST, then a single bounding box for all the objects is computed and the camera is then adjusted as above.

     If the argument is an axis object HAX, then the children of the axis are used as HANDLE_LIST.  When called with no inputs, it uses the current axis (see gca).

     camorbit, camzoom, camroll

 -- P =: campos ()
 -- campos: ([X Y Z])
 -- MODE =: campos ("mode")
 -- campos: (MODE)
 -- campos: (AX, ...)
     Set or get the camera position.

     The default camera position is determined automatically based on the scene. For example, to get the camera position:

          hf = figure();
          peaks()
          p = campos ()
            => p =
                -27.394  -35.701   64.079

     We can then move the camera further up the z-axis:

          campos (p + [0 0 10])
          campos ()
            => ans =
                -27.394  -35.701   74.079

     Having made that change, the camera position MODE is now manual:

          campos ("mode")
            => manual

     We can set it back to automatic:

          campos ("auto")
          campos ()
            => ans =
                -27.394  -35.701   64.079
          close (hf)

     By default, these commands affect the current axis; alternatively, an axis can be specified by the optional argument AX.

     camup, camtarget, camva

 -- camorbit: (THETA, PHI)
 -- camorbit: (THETA, PHI, COORSYS)
 -- camorbit: (THETA, PHI, COORSYS, DIR)
 -- camorbit: (THETA, PHI, "data")
 -- camorbit: (THETA, PHI, "data", "z")
 -- camorbit: (THETA, PHI, "data", "x")
 -- camorbit: (THETA, PHI, "data", "y")
 -- camorbit: (THETA, PHI, "data", [X Y Z])
 -- camorbit: (THETA, PHI, "camera")
 -- camorbit: (HAX, ...)
     Rotate the camera up/down and left/right around its target.

     Move the camera PHI degrees up and THETA degrees to the right, as if it were in an orbit around its target. Example:

          sphere ()
          camorbit (30, 20)

     These rotations are centered around the camera target (see camtarget). First the camera position is pitched up or down by rotating it PHI degrees around an axis orthogonal to both the viewing direction (specifically camtarget() - campos()) and the camera ``up vector'' (see camup). Example:

          camorbit (0, 20)

     The second rotation depends on the coordinate system COORSYS and direction DIR inputs. The default for COORSYS is "data".  In this case, the camera is yawed left or right by rotating it THETA degrees around an axis specified by DIR. The default for DIR is "z", corresponding to the vector [0, 0, 1]. Example:

          camorbit (30, 0)

     When COORSYS is set to "camera", the camera is moved left or right by rotating it around an axis parallel to the camera up vector (see camup). The input DIR should not be specified in this case. Example:

          camorbit (30, 0, "camera")

     (Note: the rotation by PHI is unaffected by "camera".)

     The camorbit command modifies two camera properties: see campos and see camup.

     By default, this command affects the current axis; alternatively, an axis can be specified by the optional argument HAX.

     camzoom, camroll, camlookat

 -- camroll: (THETA)
 -- camroll: (AX, THETA)
     Roll the camera.

     Roll the camera clockwise by THETA degrees. For example, the following command will roll the camera by 30 degrees clockwise (to the right); this will cause the scene to appear to roll by 30 degrees to the left:

          peaks ()
          camroll (30)

     Roll the camera back:

          camroll (-30)

     The following command restores the default camera roll:

          camup ("auto")

     By default, these commands affect the current axis; alternatively, an axis can be specified by the optional argument AX.

     camzoom, camorbit, camlookat, camup

 -- T =: camtarget ()
 -- camtarget: ([X Y Z])
 -- MODE =: camtarget ("mode")
 -- camtarget: (MODE)
 -- camtarget: (AX, ...)
     Set or get where the camera is pointed.

     The camera target is a point in space where the camera is pointing. Usually, it is determined automatically based on the scene:

          hf = figure();
          sphere (36)
          v = camtarget ()
            => v =
                0   0   0

     We can turn the camera to point at a new target:

          camtarget ([1 1 1])
          camtarget ()
            =>   1   1   1

     Having done so, the camera target MODE is manual:

          camtarget ("mode")
            => manual

     This means, for example, adding new objects to the scene will not retarget the camera:

          hold on;
          peaks ()
          camtarget ()
            =>   1   1   1

     We can reset it to be automatic:

          camtarget ("auto")
          camtarget ()
            =>   0   0   0.76426
          close (hf)

     By default, these commands affect the current axis; alternatively, an axis can be specified by the optional argument AX.

     campos, camup, camva

 -- UP =: camup ()
 -- camup: ([X Y Z])
 -- MODE =: camup ("mode")
 -- camup: (MODE)
 -- camup: (AX, ...)
     Set or get the camera up vector.

     By default, the camera is oriented so that ``up'' corresponds to the positive z-axis:

          hf = figure ();
          sphere (36)
          v = camup ()
            => v =
                0   0   1

     Specifying a new ``up vector'' rolls the camera and sets the mode to manual:

          camup ([1 1 0])
          camup ()
            =>   1   1   0
          camup ("mode")
            => manual

     Modifying the up vector does not modify the camera target (see camtarget).  Thus, the camera up vector might not be orthogonal to the direction of the camera's view:

          camup ([1 2 3])
          dot (camup (), camtarget () - campos ())
            => 6...

     A consequence is that ``pulling back'' on the up vector does not pitch the camera view (as that would require changing the target).  Setting the up vector is thus typically used only to roll the camera.  A more intuitive command for this purpose is see camroll.

     Finally, we can reset the up vector to automatic mode:

          camup ("auto")
          camup ()
            =>   0   0   1
          close (hf)

     By default, these commands affect the current axis; alternatively, an axis can be specified by the optional argument AX.

     campos, camtarget, camva

 -- A =: camva ()
 -- camva: (A)
 -- MODE =: camva ("mode")
 -- camva: (MODE)
 -- camva: (AX, ...)
     Set or get the camera viewing angle.

     The camera has a viewing angle which determines how much can be seen.  By default this is:

          hf = figure();
          sphere (36)
          a = camva ()
            => a =  10.340

     To get a wider-angle view, we could double the viewing angle.  This will also set the mode to manual:

          camva (2*a)
          camva ("mode")
            => manual

     We can set it back to automatic:

          camva ("auto")
          camva ("mode")
            => auto
          camva ()
            => ans =  10.340
          close (hf)

     By default, these commands affect the current axis; alternatively, an axis can be specified by the optional argument AX.

     campos, camtarget, camup

 -- camzoom: (ZF)
 -- camzoom: (AX, ZF)
     Zoom the camera in or out.

     A value of ZF larger than 1 ``zooms in'' such that the scene appears magnified:

          hf = figure ();
          sphere (36)
          camzoom (1.2)

     A value smaller than 1 ``zooms out'' so the camera can see more of the scene:

          camzoom (0.5)

     Technically speaking, zooming affects the ``viewing angle''.  The following command resets to the default zoom:

          camva ("auto")
          close (hf)

     By default, these commands affect the current axis; alternatively, an axis can be specified by the optional argument AX.

     camroll, camorbit, camlookat, camva

 -- slice: (X, Y, Z, V, SX, SY, SZ)
 -- slice: (X, Y, Z, V, XI, YI, ZI)
 -- slice: (V, SX, SY, SZ)
 -- slice: (V, XI, YI, ZI)
 -- slice: (..., METHOD)
 -- slice: (HAX, ...)
 -- H =: slice (...)
     Plot slices of 3-D data/scalar fields.

     Each element of the 3-dimensional array V represents a scalar value at a location given by the parameters X, Y, and Z.  The parameters X, X, and Z are either 3-dimensional arrays of the same size as the array V in the "meshgrid" format or vectors.  The parameters XI, etc. respect a similar format to X, etc., and they represent the points at which the array VI is interpolated using interp3.  The vectors SX, SY, and SZ contain points of orthogonal slices of the respective axes.

     If X, Y, Z are omitted, they are assumed to be x = 1:size (V, 2), y = 1:size (V, 1) and z = 1:size (V, 3).

     METHOD is one of:

     "nearest"
          Return the nearest neighbor.

     "linear"
          Linear interpolation from nearest neighbors.

     "cubic"
          Cubic interpolation from four nearest neighbors (not implemented yet).

     "spline"
          Cubic spline interpolation---smooth first and second derivatives throughout the curve.

     The default method is "linear".

     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.

     Examples:

          [x, y, z] = meshgrid (linspace (-8, 8, 32));
          v = sin (sqrt (x.^2 + y.^2 + z.^2)) ./ (sqrt (x.^2 + y.^2 + z.^2));
          slice (x, y, z, v, [], 0, []);

          [xi, yi] = meshgrid (linspace (-7, 7));
          zi = xi + yi;
          slice (x, y, z, v, xi, yi, zi);

     interp3, surface, pcolor

 -- ribbon: (Y)
 -- ribbon: (X, Y)
 -- ribbon: (X, Y, WIDTH)
 -- ribbon: (HAX, ...)
 -- H =: ribbon (...)
     Draw a ribbon plot for the columns of Y vs. X.

     If X is omitted, a vector containing the row numbers is assumed (1:rows (Y)).  Alternatively, X can also be a vector with same number of elements as rows of Y in which case the same X is used for each column of Y.

     The optional parameter WIDTH specifies the width of a single ribbon (default is 0.75).

     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 vector of graphics handles to the surface objects representing each ribbon. surface, waterfall

 -- shading: (TYPE)
 -- shading: (HAX, TYPE)
     Set the shading of patch or surface graphic objects.

     Valid arguments for TYPE are

     "flat"
          Single colored patches with invisible edges.

     "faceted"
          Single colored patches with black edges.

     "interp"
          Colors between patch vertices are interpolated and the patch edges are invisible.

     If the first argument HAX is an axes handle, then plot into this axes, rather than the current axes returned by gca. fill, mesh, patch, pcolor, surf, surface, hidden, lighting

 -- scatter3: (X, Y, Z)
 -- scatter3: (X, Y, Z, S)
 -- scatter3: (X, Y, Z, S, C)
 -- scatter3: (..., STYLE)
 -- scatter3: (..., "filled")
 -- scatter3: (..., PROP, VAL)
 -- scatter3: (HAX, ...)
 -- H =: scatter3 (...)
     Draw a 3-D scatter plot.

     A marker is plotted at each point defined by the coordinates in the vectors X, Y, and Z.

     The size of the markers is determined by S, which can be a scalar or a vector of the same length as X, Y, and Z.  If S is not given, or is an empty matrix, then a default value of 8 points is used.

     The color of the markers is determined by C, which can be a string defining a fixed color; a 3-element vector giving the red, green, and blue components of the color; a vector of the same length as X that gives a scaled index into the current colormap; or an Nx3 matrix defining the RGB color of each marker individually.

     The marker to use can be changed with the STYLE argument, that is a string defining a marker in the same manner as the plot command. If no marker is specified it defaults to "o" or circles. If the argument "filled" is given then the markers are filled.

     Additional property/value pairs are passed directly to the underlying patch 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 hggroup object representing the points.

          [x, y, z] = peaks (20);
          scatter3 (x(:), y(:), z(:), [], z(:));

     scatter, patch, plot

 -- waterfall: (X, Y, Z)
 -- waterfall: (Z)
 -- waterfall: (..., C)
 -- waterfall: (..., PROP, VAL, ...)
 -- waterfall: (HAX, ...)
 -- H =: waterfall (...)
     Plot a 3-D waterfall plot.

     A waterfall plot is similar to a meshz plot except only mesh lines for the rows of Z (x-values) are shown.

     The wireframe mesh is plotted using rectangles.  The vertices of the rectangles [X, Y] are typically the output of meshgrid. over a 2-D rectangular region in the x-y plane.  Z determines the height above the plane of each vertex.  If only a single Z matrix is given, then it is plotted over the meshgrid X = 1:columns (Z), Y = 1:rows (Z). Thus, columns of Z correspond to different X values and rows of Z correspond to different Y values.

     The color of the mesh is computed by linearly scaling the Z values to fit the range of the current colormap.  Use caxis and/or change the colormap to control the appearance.

     Optionally the color of the mesh can be specified independently of Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying 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.

     meshz, mesh, meshc, contour, surf, surface, ribbon, meshgrid, hidden, shading, colormap, caxis

Aspect Ratio
............

For three-dimensional plots the aspect ratio can be set for data with daspect and for the plot box with pbaspect. See Axis Configuration, for controlling the x-, y-, and z-limits for plotting.

 -- DATA_ASPECT_RATIO =: daspect ()
 -- daspect: (DATA_ASPECT_RATIO)
 -- daspect: (MODE)
 -- DATA_ASPECT_RATIO_MODE =: daspect ("mode")
 -- daspect: (HAX, ...)
     Query or set the data aspect ratio of the current axes.

     The aspect ratio is a normalized 3-element vector representing the span of the x, y, and z-axis limits.

     daspect (MODE)

     Set the data aspect ratio mode of the current axes.  MODE is either "auto" or "manual".

     daspect ("mode")

     Return the data aspect ratio mode of the current axes.

     daspect (HAX, ...)

     Operate on the axes in handle HAX instead of the current axes.

     axis, pbaspect, xlim, ylim, zlim

 -- PLOT_BOX_ASPECT_RATIO =: pbaspect ( )
 -- pbaspect: (PLOT_BOX_ASPECT_RATIO)
 -- pbaspect: (MODE)
 -- PLOT_BOX_ASPECT_RATIO_MODE =: pbaspect ("mode")
 -- pbaspect: (HAX, ...)

     Query or set the plot box aspect ratio of the current axes.

     The aspect ratio is a normalized 3-element vector representing the rendered lengths of the x, y, and z axes.

     pbaspect(MODE)

     Set the plot box aspect ratio mode of the current axes.  MODE is either "auto" or "manual".

     pbaspect ("mode")

     Return the plot box aspect ratio mode of the current axes.

     pbaspect (HAX, ...)

     Operate on the axes in handle HAX instead of the current axes.

     axis, daspect, xlim, ylim, zlim

Three-dimensional Function Plotting
...................................

 -- ezplot3: (FX, FY, FZ)
 -- ezplot3: (..., DOM)
 -- ezplot3: (..., N)
 -- ezplot3: (..., "animate")
 -- ezplot3: (HAX, ...)
 -- H =: ezplot3 (...)

     Plot a parametrically defined curve in three dimensions.

     FX, FY, and FZ are strings, inline functions, or function handles with one argument defining the function.  By default the plot is over the domain 0 <= T <= 2*pi with 500 points.

     If DOM is a two element vector, it represents the minimum and maximum values of T.

     N is a scalar defining the number of points to use in plotting the function.

     If the "animate" option is given then the plotting is animated in the style of comet3.

     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 plot.

          fx = @(t) cos (t);
          fy = @(t) sin (t);
          fz = @(t) t;
          ezplot3 (fx, fy, fz, [0, 10*pi], 100);

     plot3, comet3, ezplot, ezmesh, ezsurf

 -- ezmesh: (F)
 -- ezmesh: (FX, FY, FZ)
 -- ezmesh: (..., DOM)
 -- ezmesh: (..., N)
 -- ezmesh: (..., "circ")
 -- ezmesh: (HAX, ...)
 -- H =: ezmesh (...)

     Plot the mesh defined by a function.

     F is a string, inline function, or function handle with two arguments defining the function.  By default the plot is over the meshed domain -2*pi <= X | Y <= 2*pi with 60 points in each dimension.

     If three functions are passed, then plot the parametrically defined function [FX(S, T), FY(S, T), FZ(S, T)].

     If DOM is a two element vector, it represents the minimum and maximum values of both X and Y.  If DOM is a four element vector, then the minimum and maximum values are [xmin xmax ymin ymax].

     N is a scalar defining the number of points to use in each dimension.

     If the argument "circ" is given, then the function is plotted over a disk centered on the middle of the domain DOM.

     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.

     Example 1: 2-argument function

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezmesh (f, [-3, 3]);

     Example 2: parametrically defined function

          fx = @(s,t) cos (s) .* cos (t);
          fy = @(s,t) sin (s) .* cos (t);
          fz = @(s,t) sin (t);
          ezmesh (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20);

     mesh, ezmeshc, ezplot, ezsurf, ezsurfc, hidden

 -- ezmeshc: (F)
 -- ezmeshc: (FX, FY, FZ)
 -- ezmeshc: (..., DOM)
 -- ezmeshc: (..., N)
 -- ezmeshc: (..., "circ")
 -- ezmeshc: (HAX, ...)
 -- H =: ezmeshc (...)

     Plot the mesh and contour lines defined by a function.

     F is a string, inline function, or function handle with two arguments defining the function.  By default the plot is over the meshed domain -2*pi <= X | Y <= 2*pi with 60 points in each dimension.

     If three functions are passed, then plot the parametrically defined function [FX(S, T), FY(S, T), FZ(S, T)].

     If DOM is a two element vector, it represents the minimum and maximum values of both X and Y.  If DOM is a four element vector, then the minimum and maximum values are [xmin xmax ymin ymax].

     N is a scalar defining the number of points to use in each dimension.

     If the argument "circ" is given, then the function is plotted over a disk centered on the middle of the domain DOM.

     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 2-element vector with a graphics handle for the created mesh plot and a second handle for the created contour plot.

     Example: 2-argument function

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezmeshc (f, [-3, 3]);

     meshc, ezmesh, ezplot, ezsurf, ezsurfc, hidden

 -- ezsurf: (F)
 -- ezsurf: (FX, FY, FZ)
 -- ezsurf: (..., DOM)
 -- ezsurf: (..., N)
 -- ezsurf: (..., "circ")
 -- ezsurf: (HAX, ...)
 -- H =: ezsurf (...)

     Plot the surface defined by a function.

     F is a string, inline function, or function handle with two arguments defining the function.  By default the plot is over the meshed domain -2*pi <= X | Y <= 2*pi with 60 points in each dimension.

     If three functions are passed, then plot the parametrically defined function [FX(S, T), FY(S, T), FZ(S, T)].

     If DOM is a two element vector, it represents the minimum and maximum values of both X and Y.  If DOM is a four element vector, then the minimum and maximum values are [xmin xmax ymin ymax].

     N is a scalar defining the number of points to use in each dimension.

     If the argument "circ" is given, then the function is plotted over a disk centered on the middle of the domain DOM.

     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.

     Example 1: 2-argument function

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezsurf (f, [-3, 3]);

     Example 2: parametrically defined function

          fx = @(s,t) cos (s) .* cos (t);
          fy = @(s,t) sin (s) .* cos (t);
          fz = @(s,t) sin (t);
          ezsurf (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20);

     surf, ezsurfc, ezplot, ezmesh, ezmeshc, shading

 -- ezsurfc: (F)
 -- ezsurfc: (FX, FY, FZ)
 -- ezsurfc: (..., DOM)
 -- ezsurfc: (..., N)
 -- ezsurfc: (..., "circ")
 -- ezsurfc: (HAX, ...)
 -- H =: ezsurfc (...)

     Plot the surface and contour lines defined by a function.

     F is a string, inline function, or function handle with two arguments defining the function.  By default the plot is over the meshed domain -2*pi <= X | Y <= 2*pi with 60 points in each dimension.

     If three functions are passed, then plot the parametrically defined function [FX(S, T), FY(S, T), FZ(S, T)].

     If DOM is a two element vector, it represents the minimum and maximum values of both X and Y.  If DOM is a four element vector, then the minimum and maximum values are [xmin xmax ymin ymax].

     N is a scalar defining the number of points to use in each dimension.

     If the argument "circ" is given, then the function is plotted over a disk centered on the middle of the domain DOM.

     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 2-element vector with a graphics handle for the created surface plot and a second handle for the created contour plot.

     Example:

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezsurfc (f, [-3, 3]);

     surfc, ezsurf, ezplot, ezmesh, ezmeshc, shading

Three-dimensional Geometric Shapes
..................................

 -- cylinder:
 -- cylinder: (R)
 -- cylinder: (R, N)
 -- cylinder: (HAX, ...)
 -- [X, Y, Z] =: cylinder (...)
     Plot a 3-D unit cylinder.

     The optional input R is a vector specifying the radius along the unit z-axis.  The default is [1 1] indicating radius 1 at Z == 0 and at Z == 1.

     The optional input N determines the number of faces around the circumference of the cylinder.  The default value is 20.

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

     If outputs are requested cylinder returns three matrices in meshgrid format, such that surf (X, Y, Z) generates a unit cylinder.

     Example:

          [x, y, z] = cylinder (10:-1:0, 50);
          surf (x, y, z);
          title ("a cone");

     ellipsoid, rectangle, sphere

 -- sphere: ()
 -- sphere: (N)
 -- sphere: (HAX, ...)
 -- [X, Y, Z] =: sphere (...)
     Plot a 3-D unit sphere.

     The optional input N determines the number of faces around the circumference of the sphere.  The default value is 20.

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

     If outputs are requested sphere returns three matrices in meshgrid format such that surf (X, Y, Z) generates a unit sphere.

     Example:

          [x, y, z] = sphere (40);
          surf (3*x, 3*y, 3*z);
          axis equal;
          title ("sphere of radius 3");

     cylinder, ellipsoid, rectangle

 -- ellipsoid: (XC, YC, ZC, XR, YR, ZR, N)
 -- ellipsoid: (..., N)
 -- ellipsoid: (HAX, ...)
 -- [X, Y, Z] =: ellipsoid (...)
     Plot a 3-D ellipsoid.

     The inputs XC, YC, ZC specify the center of the ellipsoid. The inputs XR, YR, ZR specify the semi-major axis lengths.

     The optional input N determines the number of faces around the circumference of the cylinder.  The default value is 20.

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

     If outputs are requested ellipsoid returns three matrices in meshgrid format, such that surf (X, Y, Z) generates the ellipsoid. cylinder, rectangle, sphere

Plot Annotations
----------------

You can add titles, axis labels, legends, and arbitrary text to an existing plot.  For example:

     x = -10:0.1:10;
     plot (x, sin (x));
     title ("sin(x) for x = -10:0.1:10");
     xlabel ("x");
     ylabel ("sin (x)");
     text (pi, 0.7, "arbitrary text");
     legend ("sin (x)");

The functions grid and box may also be used to add grid and border lines to the plot.  By default, the grid is off and the border lines are on.

Finally, arrows, text and rectangular or elliptic boxes can be added to highlight parts of a plot using the annotation function.  Those objects are drawn in an invisible axes, on top of every other axes.

 -- title: (STRING)
 -- title: (STRING, PROP, VAL, ...)
 -- title: (HAX, ...)
 -- H =: title (...)
     Specify the string used as a title for the current axis.

     An optional list of PROPERTY/VALUE pairs can be used to change the appearance of the created title text 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 text object. xlabel, ylabel, zlabel, text

 -- legend: ()
 -- legend: (STR1, STR2, ...)
 -- legend: (CHARMAT)
 -- legend: ({CELLSTR})
 -- legend: (..., "location", POS)
 -- legend: (..., "orientation", ORIENT)
 -- legend: (HAX, ...)
 -- legend: (HOBJS, ...)
 -- legend: (HAX, HOBJS, ...)
 -- legend: ("OPTION")
 -- legend: (..., {CELLSTR}, PROPERTY, VALUE, ...)
 -- [HLEG, HLEG_OBJ, HPLOT, LABELS] =: legend (...)

     Display a legend for the current axes using the specified strings as labels.

     Legend entries may be specified as individual character string arguments, a character array, or a cell array of character strings.  When label names might be confused with options to legend, the labels should be protected by specifying them as a cell array of strings.

     If the first argument HAX is an axes handle, then add a legend to this axes, rather than the current axes returned by gca.

     Legend labels are associated with the axes' children; The first label is assigned to the first object that was plotted in the axes, the second label to the next object plotted, etc.  To label specific data objects, without labeling all objects, provide their graphic handles in the input HOBJS.

     The optional parameter POS specifies the location of the legend as follows:

       pos   location of the legend
       north   center top
       south   center bottom
       east   right center
       west   left center
       northeast   right top (default)
       northwest   left top
       southeast   right bottom
       southwest   left bottom

       outside   can be appended to any location string

                 which will place the legend outside the axes

     The optional parameter ORIENT determines if the legend elements are placed vertically or horizontally.  The allowed values are "vertical" (default) or "horizontal".

     The following customizations are available using OPTION:

     "show"
          Show legend on the plot

     "hide"
          Hide legend on the plot

     "toggle"
          Toggle between "hide" and "show"

     "boxon"
          Show a box around legend (default)

     "boxoff"
          Hide the box around legend

     "right"
          Place label text to the right of the keys (default)

     "left"
          Place label text to the left of the keys

     "off"
          Delete the legend object

     The legend function creates a graphics object which has various properties that can be manipulated with get/set. Alternatively, properties can be set directly when calling legend by including PROPERTY/VALUE pairs.  If using this calling form, the labels must be specified as a cell array of strings.

     The optional output values are

     hleg
          The graphics handle of the legend object.

     hleg_obj
          Graphics handles to the text, patch, and line objects which form the legend.

     hplot
          Graphics handles to the plot objects which were used in making the legend.

     labels
          A cell array of strings of the labels in the legend.

     Implementation Note: The legend label text is either provided in the call to legend or is taken from the DisplayName property of the graphics objects.  Only data objects, such as line, patch, and surface, have this property whereas axes, figures, etc. do not so they are never present in a legend.  If no labels or DisplayName properties are available, then the label text is simply "data1", "data2", ..., "dataN".  No more than 20 data labels will be automatically generated.  To label more, call legend explicitly and provide all labels.

     The legend FontSize property is initially set to 90% of the axes FontSize to which it is attached.  Use set to override this if necessary.

     A legend is implemented as an additional axes object with the tag property set to "legend".  Properties of the legend object may be manipulated directly by using set.

 -- text: (X, Y, STRING)
 -- text: (X, Y, Z, STRING)
 -- text: (..., PROP, VAL, ...)
 -- H =: text (...)
     Create a text object with text STRING at position X, Y, (Z) on the current axes.

     Multiple locations can be specified if X, Y, (Z) are vectors.  Multiple strings can be specified with a character matrix or a cell array of strings.

     Optional property/value pairs may be used to control the appearance of the text.

     The optional return value H is a vector of graphics handles to the created text objects.

     Programming Note: The full list of properties is documented at Text Properties. gtext, title, xlabel, ylabel, zlabel

See Text Properties for the properties that you can set.

 -- xlabel: (STRING)
 -- xlabel: (STRING, PROPERTY, VAL, ...)
 -- xlabel: (HAX, ...)
 -- H =: xlabel (...)
     Specify the string used to label the x-axis of the current axis.

     An optional list of PROPERTY/VALUE pairs can be used to change the properties of the created text label.

     If the first argument HAX is an axes handle, then operate on this axes rather than the current axes returned by gca.

     The optional return value H is a graphics handle to the created text object. ylabel, zlabel, datetick, title, text

 -- clabel: (C, H)
 -- clabel: (C, H, V)
 -- clabel: (C, H, "manual")
 -- clabel: (C)
 -- clabel: (..., PROP, VAL, ...)
 -- H =: clabel (...)
     Add labels to the contours of a contour plot.

     The contour levels are specified by the contour matrix C which is returned by contour, contourc, contourf, and contour3.  Contour labels are rotated to match the local line orientation and centered on the line.  The position of labels along the contour line is chosen randomly.

     If the argument H is a handle to a contour group object, then label this plot rather than the one in the current axes returned by gca.

     By default, all contours are labeled.  However, the contours to label can be specified by the vector V.  If the "manual" argument is given then the contours to label can be selected with the mouse.

     Additional property/value pairs that are valid properties of text objects can be given and are passed to the underlying text objects.  Moreover, the contour group property "LabelSpacing" is available which determines the spacing between labels on a contour to be specified.  The default is 144 points, or 2 inches.

     The optional return value H is a vector of graphics handles to the text objects representing each label. The "userdata" property of the text objects contains the numerical value of the contour label.

     An example of the use of clabel is

          [c, h] = contour (peaks (), -4 : 6);
          clabel (c, h, -4:2:6, "fontsize", 12);

     contour, contourf, contour3, meshc, surfc, text

 -- box:
 -- box: on
 -- box: off
 -- box: (HAX, ...)
     Control display of the axes border.

     The argument may be either "on" or "off".  If it is omitted, the current box state is toggled.

     If the first argument HAX is an axes handle, then operate on this axes rather than the current axes returned by gca. axis, grid

 -- grid:
 -- grid: on
 -- grid: off
 -- grid: minor
 -- grid: minor on
 -- grid: minor off
 -- grid: (HAX, ...)
     Control the display of plot grid lines.

     The function state input may be either "on" or "off". If it is omitted, the current grid state is toggled.

     When the first argument is "minor" all subsequent commands modify the minor grid rather than the major grid.

     If the first argument HAX is an axes handle, then operate on this axes rather than the current axes returned by gca.

     To control the grid lines for an individual axes use the set function.  For example:

          set (gca, "ygrid", "on");

     axis, box

 -- colorbar:
 -- colorbar: (..., LOC)
 -- colorbar: (DELETE_OPTION)
 -- colorbar: (HCB, ...)
 -- colorbar: (HAX, ...)
 -- colorbar: (..., "peer", HAX, ...)
 -- colorbar: (..., "location", LOC, ...)
 -- colorbar: (..., PROP, VAL, ...)
 -- H =: colorbar (...)
     Add a colorbar to the current axes.

     A colorbar displays the current colormap along with numerical rulings so that the color scale can be interpreted.

     The optional input LOC determines the location of the colorbar.  If present, it must be the last argument to colorbar.  Valid values for LOC are

     "EastOutside"
          Place the colorbar outside the plot to the right.  This is the default.

     "East"
          Place the colorbar inside the plot to the right.

     "WestOutside"
          Place the colorbar outside the plot to the left.

     "West"
          Place the colorbar inside the plot to the left.

     "NorthOutside"
          Place the colorbar above the plot.

     "North"
          Place the colorbar at the top of the plot.

     "SouthOutside"
          Place the colorbar under the plot.

     "South"
          Place the colorbar at the bottom of the plot.

     To remove a colorbar from a plot use any one of the following keywords for the DELETE_OPTION: "off", "delete", "hide".

     If the first argument HAX is an axes handle, then the colorbar is added to this axes, rather than the current axes returned by gca. Alternatively, If the argument "peer" is given, then the following argument is treated as the axes handle in which to add the colorbar.  The "peer" calling syntax may be removed in the future and is not recommended.

     If the first argument HCB is a handle to a colorbar object, then operate on this colorbar directly.

     Additional property/value pairs are passed directly to the underlying axes object.

     The optional return value H is a graphics handle to the created colorbar object.

     Implementation Note: A colorbar is created as an additional axes object with the "tag" property set to "colorbar".  The created object has the extra property "location" which controls the positioning of the colorbar. colormap

 -- annotation: (TYPE)
 -- annotation: ("line", X, Y)
 -- annotation: ("arrow", X, Y)
 -- annotation: ("doublearrow", X, Y)
 -- annotation: ("textarrow", X, Y)
 -- annotation: ("textbox", POS)
 -- annotation: ("rectangle", POS)
 -- annotation: ("ellipse", POS)
 -- annotation: (..., PROP, VAL)
 -- annotation: (HF, ...)
 -- H =: annotation (...)
     Draw annotations to emphasize parts of a figure.

     You may build a default annotation by specifying only the TYPE of the annotation.

     Otherwise you can select the type of annotation and then set its position using either X and Y coordinates for line-based annotations or a position vector POS for others.  In either case, coordinates are interpreted using the "units" property of the annotation object. The default is "normalized", which means the lower left hand corner of the figure has coordinates [0 0] and the upper right hand corner [1 1].

     If the first argument HF is a figure handle, then plot into this figure, rather than the current figure returned by gcf.

     Further arguments can be provided in the form of PROP/VAL pairs to customize the annotation appearance.

     The optional return value H is a graphics handle to the created annotation object.  This can be used with the set function to customize an existing annotation object.

     All annotation objects share two properties:

       * "units": the units in which coordinates are interpreted.
          Its value may be one of "centimeters" | "characters" |
          "inches" | "{normalized}" | "pixels" |
          "points".

       * "position": a four-element vector [x0 y0 width height].
          The vector specifies the coordinates (x0,y0) of the origin of the annotation object, its width, and its height.  The width and height may be negative, depending on the orientation of the object.

     Valid annotation types and their specific properties are described below:

     "line"
          Constructs a line.  X and Y must be two-element vectors specifying the x and y coordinates of the two ends of the line.

          The line can be customized using "linewidth", "linestyle", and "color" properties the same way as for line objects.

     "arrow"
          Construct an arrow.  The second point in vectors X and Y specifies the arrowhead coordinates.

          Besides line properties, the arrowhead can be customized using "headlength", "headwidth", and "headstyle" properties.  Supported values for "headstyle" property are: ["diamond" | "ellipse" | "plain" | "rectangle" | "vback1" | "{vback2}" | "vback3"]

     "doublearrow"
          Construct a double arrow.  Vectors X and Y specify the arrowhead coordinates.

          The line and the arrowhead can be customized as for arrow annotations, but some property names are duplicated: "head1length"/"head2length", "head1width"/"head2width", etc.  The index 1 marks the properties of the arrowhead at the first point in X and Y coordinates.

     "textarrow"
          Construct an arrow with a text label at the opposite end from the arrowhead.

          Use the "string" property to change the text string. The line and the arrowhead can be customized as for arrow annotations, and the text can be customized using the same properties as text graphics objects.  Note, however, that some text property names are prefixed with "text" to distinguish them from arrow properties: "textbackgroundcolor", "textcolor", "textedgecolor", "textlinewidth", "textmargin", "textrotation".

     "textbox"
          Construct a box with text inside.  POS specifies the "position" property of the annotation.

          Use the "string" property to change the text string. You may use "backgroundcolor", "edgecolor", "linestyle", and "linewidth" properties to customize the box background color and edge appearance.  A limited set of text objects properties are also available; Besides "font..." properties, you may also use "horizontalalignment" and "verticalalignment" to position the text inside the box.

          Finally, the "fitboxtotext" property controls the actual extent of the box.  If "on" (the default) the box limits are fitted to the text extent.

     "rectangle"
          Construct a rectangle.  POS specifies the "position" property of the annotation.

          You may use "facecolor", "color", "linestyle", and "linewidth" properties to customize the rectangle background color and edge appearance.

     "ellipse"
          Construct an ellipse.  POS specifies the "position" property of the annotation.

          See "rectangle" annotations for customization.

     xlabel, ylabel, zlabel, title, text, gtext, legend, colorbar

Multiple Plots on One Page
--------------------------

Octave can display more than one plot in a single figure.  The simplest way to do this is to use the subplot function to divide the plot area into a series of subplot windows that are indexed by an integer. For example,

     subplot (2, 1, 1)
     fplot (@sin, [-10, 10]);
     subplot (2, 1, 2)
     fplot (@cos, [-10, 10]);

creates a figure with two separate axes, one displaying a sine wave and the other a cosine wave.  The first call to subplot divides the figure into two plotting areas (two rows and one column) and makes the first plot area active. The grid of plot areas created by subplot is numbered in row-major order (left to right, top to bottom).  After plotting a sine wave, the next call to subplot activates the second subplot area, but does not re-partition the figure.

 -- subplot: (ROWS, COLS, INDEX)
 -- subplot: (ROWS, COLS, INDEX, HAX)
 -- subplot: (RCN)
 -- subplot: (HAX)
 -- subplot: (..., "align")
 -- subplot: (..., "replace")
 -- subplot: (..., "position", POS)
 -- subplot: (..., PROP, VAL, ...)
 -- HAX =: subplot (...)
     Set up a plot grid with ROWS by COLS subwindows and set the current axes for plotting (gca) to the location given by INDEX.

     If an axes handle HAX is provided after the (ROWS, COLS, INDEX) arguments, the corresponding axes is turned into a subplot.

     If only one numeric argument is supplied, then it must be a three digit value specifying the number of rows in digit 1, the number of columns in digit 2, and the plot index in digit 3.

     The plot index runs row-wise; First, all columns in a row are numbered and then the next row is filled.

     For example, a plot with 2x3 grid will have plot indices running as follows:

          +-----+-----+-----+
          |  1  |  2  |  3  |
          +-----+-----+-----+
          |  4  |  5  |  6  |
          +-----+-----+-----+

     INDEX may also be a vector.  In this case, the new axes will enclose the grid locations specified.  The first demo illustrates this:

          demo ("subplot", 1)

     The index of the subplot to make active may also be specified by its axes handle, HAX, returned from a previous subplot command.

     If the option "align" is given then the plot boxes of the subwindows will align, but this may leave no room for axes tick marks or labels.

     If the option "replace" is given then the subplot axes will be reset, rather than just switching the current axes for plotting to the requested subplot.

     The "position" property can be used to exactly position the subplot axes within the current figure.  The option POS is a 4-element vector [x, y, width, height] that determines the location and size of the axes. The values in POS are normalized in the range [0,1].

     Any property/value pairs are passed directly to the underlying axes object.

     If the output HAX is requested, subplot returns the axes handle for the subplot.  This is useful for modifying the properties of a subplot using set. axes, plot, gca, set

Multiple Plot Windows
---------------------

You can open multiple plot windows using the figure function. For example,

     figure (1);
     fplot (@sin, [-10, 10]);
     figure (2);
     fplot (@cos, [-10, 10]);

creates two figures, with the first displaying a sine wave and the second a cosine wave.  Figure numbers must be positive integers.

 -- figure:
 -- figure: N
 -- figure: (N)
 -- figure: (..., "PROPERTY", VALUE, ...)
 -- H =: figure (...)
     Create a new figure window for plotting.

     If no arguments are specified, a new figure with the next available number is created.

     If called with an integer N, and no such numbered figure exists, then a new figure with the specified number is created.  If the figure already exists then it is made visible and becomes the current figure for plotting.

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

     The optional return value H is a graphics handle to the created figure object.

     Programming Note: The full list of properties is documented at Figure Properties. axes, gcf, clf, close

Manipulation of Plot Objects
----------------------------

 -- pan:
 -- pan: on
 -- pan: off
 -- pan: xon
 -- pan: yon
 -- pan: (HFIG, OPTION)
     Control the interactive panning mode of a figure in the GUI.

     Given the option "on" or "off", set the interactive pan mode on or off.

     With no arguments, toggle the current pan mode on or off.

     Given the option "xon" or "yon", enable pan mode for the x or y axis only.

     If the first argument HFIG is a figure, then operate on the given figure rather than the current figure as returned by gcf.

     rotate3d, zoom

 -- rotate: (H, DIRECTION, ALPHA)
 -- rotate: (..., ORIGIN)
     Rotate the plot object H through ALPHA degrees around the line with direction DIRECTION and origin ORIGIN.

     The default value of ORIGIN is the center of the axes object that is the parent of H.

     If H is a vector of handles, they must all have the same parent axes object.

     Graphics objects that may be rotated are lines, surfaces, patches, and images.

 -- rotate3d:
 -- rotate3d: on
 -- rotate3d: off
 -- rotate3d: (HFIG, OPTION)
     Control the interactive 3-D rotation mode of a figure in the GUI.

     Given the option "on" or "off", set the interactive rotate mode on or off.

     With no arguments, toggle the current rotate mode on or off.

     If the first argument HFIG is a figure, then operate on the given figure rather than the current figure as returned by gcf.

     pan, zoom

 -- zoom:
 -- zoom: (FACTOR)
 -- zoom: on
 -- zoom: off
 -- zoom: xon
 -- zoom: yon
 -- zoom: out
 -- zoom: reset
 -- zoom: (HFIG, OPTION)
     Zoom the current axes object or control the interactive zoom mode of a figure in the GUI.

     Given a numeric argument greater than zero, zoom by the given factor.  If the zoom factor is greater than one, zoom in on the plot.  If the factor is less than one, zoom out.  If the zoom factor is a two- or three-element vector, then the elements specify the zoom factors for the x, y, and z axes respectively.

     Given the option "on" or "off", set the interactive zoom mode on or off.

     With no arguments, toggle the current zoom mode on or off.

     Given the option "xon" or "yon", enable zoom mode for the x or y-axis only.

     Given the option "out", zoom to the initial zoom setting.

     Given the option "reset", store the current zoom setting so that zoom out will return to this zoom level.

     If the first argument HFIG is a figure, then operate on the given figure rather than the current figure as returned by gcf.

     pan, rotate3d

Manipulation of Plot Windows
----------------------------

By default, Octave refreshes the plot window when a prompt is printed, or when waiting for input.  The drawnow function is used to cause a plot window to be updated.

 -- drawnow: ()
 -- drawnow: ("expose")
 -- drawnow: (TERM, FILE, DEBUG_FILE)
     Update figure windows and their children.

     The event queue is flushed and any callbacks generated are executed.

     With the optional argument "expose", only graphic objects are updated and no other events or callbacks are processed.

     The third calling form of drawnow is for debugging and is undocumented. refresh

Only figures that are modified will be updated.  The refresh function can also be used to cause an update of the current figure, even if it is not modified.

 -- refresh: ()
 -- refresh: (H)
     Refresh a figure, forcing it to be redrawn.

     When called without an argument the current figure is redrawn.  Otherwise, the figure with graphic handle H is redrawn. drawnow

Normally, high-level plot functions like plot or mesh call newplot to initialize the state of the current axes so that the next plot is drawn in a blank window with default property settings.  To have two plots superimposed over one another, use the hold function.  For example,

     hold on;
     x = -10:0.1:10;
     plot (x, sin (x));
     plot (x, cos (x));
     hold off;

displays sine and cosine waves on the same axes.  If the hold state is off, consecutive plotting commands like this will only display the last plot.

 -- newplot: ()
 -- newplot: (HFIG)
 -- newplot: (HAX)
 -- HAX =: newplot (...)
     Prepare graphics engine to produce a new plot.

     This function is called at the beginning of all high-level plotting functions.  It is not normally required in user programs.  newplot queries the "NextPlot" field of the current figure and axes to determine what to do.

     Figure NextPlot   Action
     "new"   Create a new figure and make it the current figure.

     "add" (default)   Add new graphic objects to the current
     figure.

     "replacechildren"   Delete child objects whose
     HandleVisibility is set to "on".  Set NextPlot property to
     "add".  This typically clears a figure, but leaves in place hidden
     objects such as menubars.  This is equivalent to clf.

     "replace"   Delete all child objects of the figure and
     reset all figure properties to their defaults.  However, the following
     four properties are not reset: Position, Units, PaperPosition, PaperUnits.
     This is equivalent to clf reset.

     Axes NextPlot   Action
     "add"   Add new graphic objects to the current axes.  This
     is equivalent to hold on.

     "replacechildren"   Delete child objects whose
     HandleVisibility is set to "on", but leave axes properties
     unmodified.  This typically clears a plot, but preserves special settings
     such as log scaling for axes.  This is equivalent to cla.

     "replace" (default)   Delete all child objects of the
     axes and reset all axes properties to their defaults.  However, the
     following properties are not reset: Position, Units.  This is equivalent
     to cla reset.

     If the optional input HFIG or HAX is given then prepare the specified figure or axes rather than the current figure and axes.

     The optional return value HAX is a graphics handle to the created axes object (not figure).

     Caution: Calling newplot may change the current figure and current axes.

 -- hold:
 -- hold: on
 -- hold: off
 -- hold: (HAX, ...)
     Toggle or set the "hold" state of the plotting engine which determines whether new graphic objects are added to the plot or replace the existing objects.

     hold on
          Retain plot data and settings so that subsequent plot commands are displayed on a single graph.  Line color and line style are advanced for each new plot added.

     hold all (deprecated)
          Equivalent to hold on.

     hold off
          Restore default graphics settings which clear the graph and reset axes properties before each new plot command.  (default).

     hold
          Toggle the current hold state.

     When given the additional argument HAX, the hold state is modified for this axes rather than the current axes returned by gca.

     To query the current hold state use the ishold function. ishold, cla, clf, newplot

 -- ishold:
 -- ishold: (HAX)
 -- ishold: (HFIG)
     Return true if the next plot will be added to the current plot, or false if the plot device will be cleared before drawing the next plot.

     If the first argument is an axes handle HAX or figure handle HFIG then operate on this plot rather than the current one. hold, newplot

To clear the current figure, call the clf function.  To clear the current axis, call the cla function.  To bring the current figure to the top of the window stack, call the shg function.  To delete a graphics object, call delete on its index.  To close the figure window, call the close function.

 -- clf:
 -- clf: reset
 -- clf: (HFIG)
 -- clf: (HFIG, "reset")
 -- H =: clf (...)
     Clear the current figure window.

     clf operates by deleting child graphics objects with visible handles (HandleVisibility = "on").

     If the optional argument "reset" is specified, delete all child objects including those with hidden handles and reset all figure properties to their defaults.  However, the following properties are not reset: Position, Units, PaperPosition, PaperUnits.

     If the first argument HFIG is a figure handle, then operate on this figure rather than the current figure returned by gcf.

     The optional return value H is the graphics handle of the figure window that was cleared. cla, close, delete, reset

 -- cla:
 -- cla: reset
 -- cla: (HAX)
 -- cla: (HAX, "reset")
     Clear the current or specified (HAX) axes object.

     cla operates by deleting child graphic objects with visible handles (HandleVisibility = "on").  This typically clears the axes of any visual objects, but leaves in place axes limits, tick marks and labels, camera view, etc.  In addition, the automatic coloring and styling of lines is reset by changing the axes properties ColorOrderIndex, LinestyleOrderIndex to 1.

     If the optional argument "reset" is specified, delete all child objects, including those with hidden handles, and reset all axes properties to their defaults.  However, the following properties are not reset: Position, Units.

     If the first argument HAX is an axes handle, then operate on this axes rather than the current axes returned by gca. clf, delete, reset

 -- shg:
     Show the graph window.

     Currently, this is the same as executing drawnow. drawnow, figure

 -- delete: (FILE)
 -- delete: (FILE1, FILE2, ...)
 -- delete: (HANDLE)
     Delete the named file or graphics handle.

     FILE may contain globbing patterns such as *.  Multiple files to be deleted may be specified in the same function call.

     HANDLE may be a scalar or vector of graphic handles to delete.

     Programming Note: Deleting graphics objects is the proper way to remove features from a plot without clearing the entire figure. clf, cla, unlink, rmdir

 -- close:
 -- close: (H)
 -- close: FIGNAME
 -- close: all
 -- close: all hidden
 -- close: all force
     Close figure window(s).

     When called with no arguments, close the current figure.  This is equivalent to close (gcf).  If the input H is a graphic handle, or vector of graphics handles, then close each figure in H.  The figure to close may also be specified by name FIGNAME which is matched against the "Name" property of all figures.

     If the argument "all" is given then all figures with visible handles (HandleVisibility = "on") are closed.

     If the additional argument "hidden" is given then all figures, including hidden ones, are closed.

     If the additional argument "force" is given then figures are closed even when "closerequestfcn" has been altered to prevent closing the window.

     Implementation Note: close operates by making the handle H the current figure, and then calling the function specified by the "closerequestfcn" property of the figure.  By default, the function closereq is used.  It is possible that the function invoked will delay or abort removing the figure.  To remove a figure without executing any callback functions use delete.  When writing a callback function to close a window do not use close to avoid recursion.

     closereq, delete

 -- closereq: ()
     Close the current figure and delete all graphics objects associated with it.

     By default, the "closerequestfcn" property of a new plot figure points to this function. close, delete

Use of the interpreter Property
-------------------------------

All text objects---such as titles, labels, legends, and text---include the property "interpreter" that determines the manner in which special control sequences in the text are rendered.

The interpreter property can take three values: "none", "tex", "latex".  If the interpreter is set to "none" then no special rendering occurs---the displayed text is a verbatim copy of the specified text. Currently, the "latex" interpreter is not implemented for on-screen display and is equivalent to "none".  Note that Octave does not parse or validate the text strings when in "latex" mode---it is the responsibility of the programmer to generate valid strings which may include wrapping sections that should appear in Math mode with '$' characters.

The "tex" option implements a subset of TeX functionality when rendering text.  This allows the insertion of special glyphs such as Greek characters or mathematical symbols.  Special characters are inserted by using a backslash (\) character followed by a code, as shown in tab:extended.

Besides special glyphs, the formatting of the text can be changed within the string by using the codes

  \bf   Bold font
  \it   Italic font
  \sl   Oblique Font
  \rm   Normal font

These codes may be used in conjunction with the { and } characters to limit the change to a part of the string.  For example,

     xlabel ('{\bf H} = a {\bf V}')

where the character 'a' will not appear in bold font.  Note that to avoid having Octave interpret the backslash character in the strings, the strings themselves should be in single quotes.

It is also possible to change the fontname and size within the text

  \fontname{FONTNAME}   Specify the font to use
  \fontsize{SIZE}   Specify the size of the font to
use

The color of the text may also be changed inline using either a string (e.g., "red") or numerically with a Red-Green-Blue (RGB) specification (e.g., [1 0 0], also red).

  \color{COLOR}   Specify the color as a string
  \color[rgb]{R G B}   Specify the color
numerically

Finally, superscripting and subscripting can be controlled with the '^' and '_' characters.  If the '^' or '_' is followed by a { character, then all of the block surrounded by the { } pair is superscripted or subscripted.  Without the { } pair, only the character immediately following the '^' or '_' is changed.

Greek Lowercase Letters
   \alpha         \beta           \gamma
   \delta         \epsilon        \zeta
   \eta           \theta          \vartheta
   \iota          \kappa          \lambda
   \mu            \nu             \xi
   \o             \pi             \varpi
   \rho           \sigma          \varsigma
   \tau           \upsilon        \phi
   \chi           \psi            \omega
Greek Uppercase Letters
   \Gamma         \Delta          \Theta
   \Lambda        \Xi             \Pi
   \Sigma         \Upsilon        \Phi
   \Psi           \Omega
Misc Symbols Type Ord
   \aleph         \wp             \Re
   \Im            \partial        \infty
   \prime         \nabla          \surd
   \angle         \forall         \exists
   \neg           \clubsuit       \diamondsuit
   \heartsuit     \spadesuit
``Large'' Operators
   \int
Binary Operators
   \pm            \cdot           \times
   \ast           \circ           \bullet
   \div           \cap            \cup
   \vee           \wedge          \oplus
   \otimes        \oslash
Relations
   \leq           \subset         \subseteq
   \in            \geq            \supset
   \supseteq      \ni             \mid
   \equiv         \sim            \approx
   \cong          \propto         \perp
Arrows
   \leftarrow     \Leftarrow      \rightarrow
   \Rightarrow    \leftrightarrow    \uparrow
   \downarrow
Openings and Closings
   \lfloor        \langle         \lceil
   \rfloor        \rangle         \rceil
Alternate Names
   \neq
Other
   \ldots         \0             \copyright
   \deg

Table: Available special characters in TeX mode

Degree Symbol
.............

Conformance to both TeX and MATLAB with respect to the \circ symbol is impossible.  While TeX translates this symbol to Unicode 2218 (U+2218), MATLAB maps this to Unicode 00B0 (U+00B0) instead.  Octave has chosen to follow the TeX specification, but has added the additional symbol \deg which maps to the degree symbol (U+00B0).

Printing and Saving Plots
-------------------------

The print command allows you to send plots to you printer and to save plots in a variety of formats.  For example,

     print -dpsc

prints the current figure to a color PostScript printer.  And,

     print -deps foo.eps

saves the current figure to an encapsulated PostScript file called foo.eps.

The current graphic toolkits produce very similar graphic displays, but differ in their capability to display unusual text and in their ability to print such text.  In general, the "tex" interpreter (default) is the best all-around performer for both on-screen display and printing.  However, for the reproduction of complicated text formulas the "latex" interpreter is preferred.  The "latex" interpreter will not display symbols on-screen, but the printed output will be correct.  When printing, use one of the standalone options which provide full access to LaTeX commands.

A complete example showing the capabilities of text printing using the -dpdflatexstandalone option is:

     x = 0:0.01:3;
     hf = figure ();
     plot (x, erf (x));
     hold on;
     plot (x, x, "r");
     axis ([0, 3, 0, 1]);
     text (0.65, 0.6175, ['$\displaystyle\leftarrow x = {2 \over \sqrt{\pi}}'...
                          '\int_{0}^{x} e^{-t^2} dt = 0.6175$'],
           "interpreter", "latex");
     xlabel ("x");
     ylabel ("erf (x)");
     title ("erf (x) with text annotation");
     print (hf, "plot15_7.pdf", "-dpdflatexstandalone");
     system ("pdflatex plot15_7");
     open plot15_7.pdf

 -- print: ()
 -- print: (OPTIONS)
 -- print: (FILENAME, OPTIONS)
 -- print: (H, FILENAME, OPTIONS)
     Print a plot, or save it to a file.

     Both output formatted for printing (PDF and PostScript), and many bitmapped and vector image formats are supported.

     FILENAME defines the name of the output file.  If the filename has no suffix, one is inferred from the specified device and appended to the filename.  If no filename is specified, the output is sent to the printer.

     H specifies the handle of the figure to print.  If no handle is specified the current figure is used.

     For output to a printer, PostScript file, or PDF file, the paper size is specified by the figure's papersize property.  The location and size of the image on the page are specified by the figure's paperposition property.  The orientation of the page is specified by the figure's paperorientation property.

     The width and height of images are specified by the figure's paperposition(3:4) property values.

     The print command supports many OPTIONS:

     -fH
          Specify the handle, H, of the figure to be printed.  The default is the current figure.

     -PPRINTER
          Set the PRINTER name to which the plot is sent if no FILENAME is specified.

     -GGHOSTSCRIPT_COMMAND
          Specify the command for calling Ghostscript.  For Unix and Windows the defaults are "gs" and "gswin32c", respectively.

     -color
     -mono
          Color or monochrome output.

     -solid
     -dashed
          Force all lines to be solid or dashed, respectively.

     -portrait
     -landscape
          Specify the orientation of the plot for printed output. For non-printed output the aspect ratio of the output corresponds to the plot area defined by the "paperposition" property in the orientation specified.  This option is equivalent to changing the figure's "paperorientation" property.

     -TextAlphaBits=N
     -GraphicsAlphaBits=N
          Octave is able to produce output for various printers, bitmaps, and vector formats by using Ghostscript.  For bitmap and printer output anti-aliasing is applied using Ghostscript's TextAlphaBits and GraphicsAlphaBits options.  The default number of bits are 4 and 1 respectively.  Allowed values for N are 1, 2, or 4.

     -dDEVICE
          The available output format is specified by the option DEVICE, and is one of:

          ps
          ps2
          psc
          psc2
               PostScript (level 1 and 2, mono and color).  The OpenGL-based toolkits always generate PostScript level 3.0.

          eps
          eps2
          epsc
          epsc2
               Encapsulated PostScript (level 1 and 2, mono and color).  The OpenGL-based toolkits always generate PostScript level 3.0.

          pslatex
          epslatex
          pdflatex
          pslatexstandalone
          epslatexstandalone
          pdflatexstandalone
               Generate a LaTeX file FILENAME.tex for the text portions of a plot and a file FILENAME.(ps|eps|pdf) for the remaining graphics.  The graphics file suffix .ps|eps|pdf is determined by the specified device type.  The LaTeX file produced by the standalone option can be processed directly by LaTeX.  The file generated without the standalone option is intended to be included from another LaTeX document.  In either case, the LaTeX file contains an \includegraphics command so that the generated graphics file is automatically included when the LaTeX file is processed.  The text that is written to the LaTeX file contains the strings exactly as they were specified in the plot.  If any special characters of the TeX mode interpreter were used, the file must be edited before LaTeX processing.  Specifically, the special characters must be enclosed with dollar signs ($ ... $), and other characters that are recognized by LaTeX may also need editing (.e.g., braces).  The pdflatex device, and any of the standalone formats, are not available with the Gnuplot toolkit.

          epscairo
          pdfcairo
          epscairolatex
          pdfcairolatex
          epscairolatexstandalone
          pdfcairolatexstandalone
               Generate Cairo based output when using the Gnuplot graphics toolkit. The epscairo and pdfcairo devices are synonymous with the epsc device.  The LaTeX variants generate a LaTeX file, FILENAME.tex, for the text portions of a plot, and an image file, FILENAME.(eps|pdf), for the graph portion of the plot. The standalone variants behave as described for epslatexstandalone above.

          ill
          aifm
               Adobe Illustrator (Obsolete for Gnuplot versions > 4.2)

          canvas
               Javascript-based drawing on HTML5 canvas viewable in a web browser (only available for the Gnuplot graphics toolkit).

          cdr
          corel
               CorelDraw

          cgm
               Computer Graphics Metafile, Version 1, ANSI X3.122-1986 (only available for the Gnuplot graphics toolkit).

          dxf
               AutoCAD

          emf
          meta
               Microsoft Enhanced Metafile

          fig
               XFig.  For the Gnuplot graphics toolkit, the additional options -textspecial or -textnormal can be used to control whether the special flag should be set for the text in the figure. (default is -textnormal)

          gif
               GIF image (only available for the Gnuplot graphics toolkit).

          hpgl
               HP plotter language

          jpg
          jpeg
               JPEG image

          latex
          eepic
               LaTeX picture environment and extended picture environment (only available for the Gnuplot graphics toolkit).

          mf
               Metafont

          png
               Portable network graphics

          pbm
               PBMplus

          pdf
               Portable document format

          svg
               Scalable vector graphics

          tikz
          tikzstandalone
               Generate a LaTeX file using PGF/TikZ format.  The OpenGL-based toolkits create a PGF file while Gnuplot creates a TikZ file.  The tikzstandalone device produces a LaTeX document which includes the TikZ file (tikzstandalone and is only available for the Gnuplot graphics toolkit).

          If the device is omitted, it is inferred from the file extension, or if there is no filename it is sent to the printer as PostScript.

     -dGHOSTSCRIPT_DEVICE
          Additional devices are supported by Ghostscript. Some examples are;

          pdfwrite
               Produces pdf output from eps

          ljet2p
               HP LaserJet IIP

          pcx24b
               24-bit color PCX file format

          ppm
               Portable Pixel Map file format

          For a complete list, type system ("gs -h") to see what formats and devices are available.

          When Ghostscript output is sent to a printer the size is determined by the figure's "papersize" property.  When the output is sent to a file the size is determined by the plot box defined by the figure's "paperposition" property.

     -append
          Append PostScript or PDF output to a pre-existing file of the same type.

     -rNUM
          Resolution of bitmaps in pixels per inch.  For both metafiles and SVG the default is the screen resolution; for other formats it is 150 dpi.  To specify screen resolution, use "-r0".

     -loose
     -tight
          Force a tight or loose bounding box for eps files.  The default is loose.

     -PREVIEW
          Add a preview to eps files.  Supported formats are:

          -interchange
               Provide an interchange preview.

          -metafile
               Provide a metafile preview.

          -pict
               Provide pict preview.

          -tiff
               Provide a tiff preview.

     -SXSIZE,YSIZE
          Plot size in pixels for EMF, GIF, JPEG, PBM, PNG, and SVG. For PS, EPS, PDF, and other vector formats the plot size is in points. This option is equivalent to changing the size of the plot box associated with the "paperposition" property.  When using the command form of the print function you must quote the XSIZE,YSIZE option.  For example, by writing "-S640,480".

     -FFONTNAME
     -FFONTNAME:SIZE
     -F:SIZE
          Use FONTNAME and/or FONTSIZE for all text. FONTNAME is ignored for some devices: dxf, fig, hpgl, etc.

     The filename and options can be given in any order.

     Example: Print to a file using the pdf device.

          figure (1);
          clf ();
          surf (peaks);
          print figure1.pdf

     Example: Print to a file using jpg device.

          clf ();
          surf (peaks);
          print -djpg figure2.jpg

     Example: Print to printer named PS_printer using ps format.

          clf ();
          surf (peaks);
          print -dpswrite -PPS_printer

     saveas, hgsave, orient, figure

 -- saveas: (H, FILENAME)
 -- saveas: (H, FILENAME, FMT)
     Save graphic object H to the file FILENAME in graphic format FMT.

     All device formats accepted by print may be used.  Common formats are:

     ps
          PostScript

     eps
          Encapsulated PostScript

     pdf
          Portable Document Format

     jpg
          JPEG Image

     png
          PNG Image

     emf
          Enhanced Meta File

     If FMT is omitted it is extracted from the extension of FILENAME.  The default format when there is no extension is "pdf".

          clf ();
          surf (peaks);
          saveas (1, "figure1.png");

     print, hgsave, orient

 -- orient: (ORIENTATION)
 -- orient: (HFIG, ORIENTATION)
 -- ORIENTATION =: orient ()
 -- ORIENTATION =: orient (HFIG)
     Query or set the print orientation for figure HFIG.

     Valid values for ORIENTATION are "portrait", "landscape", and "tall".

     The "landscape" option changes the orientation so the plot width is larger than the plot height.  The "paperposition" is also modified so that the plot fills the page, while leaving a 0.25 inch border.

     The "tall" option sets the orientation to "portrait" and fills the page with the plot, while leaving a 0.25 inch border.

     The "portrait" option (default) changes the orientation so the plot height is larger than the plot width.  It also restores the default "paperposition" property.

     When called with no arguments, return the current print orientation.

     If the argument HFIG is omitted, then operate on the current figure returned by gcf. print, saveas

print and saveas are used when work on a plot has finished and the output must be in a publication-ready format.  During intermediate stages it is often better to save the graphics object and all of its associated information so that changes---to colors, axis limits, marker styles, etc.---can be made easily from within Octave.  The hgsave/hgload commands can be used to save and re-create a graphics object.

 -- hgsave: (FILENAME)
 -- hgsave: (H, FILENAME)
 -- hgsave: (H, FILENAME, FMT)
     Save the graphics handle H to the file FILENAME in the format FMT.

     If unspecified, H is the current figure as returned by gcf.

     When FILENAME does not have an extension the default filename extension .ofig will be appended.

     If present, FMT should be one of the following:

       * -binary, -float-binary

       * -hdf5, -float-hdf5

       * -V7, -v7, -7, -mat7-binary

       * -V6, -v6, -6, -mat6-binary

       * -text

       * -zip, -z

     When producing graphics for final publication use print or saveas.  When it is important to be able to continue to edit a figure as an Octave object, use hgsave/hgload. hgload, hdl2struct, saveas, print

 -- H =: hgload (FILENAME)
     Load the graphics object in FILENAME into the graphics handle H.

     If FILENAME has no extension, Octave will try to find the file with and without the standard extension of .ofig. hgsave, struct2hdl

Interacting with Plots
----------------------

The user can select points on a plot with the ginput function or select the position at which to place text on the plot with the gtext function using the mouse.

 -- [X, Y, BUTTONS] =: ginput (N)
 -- [X, Y, BUTTONS] =: ginput ()
     Return the position and type of mouse button clicks and/or key strokes in the current figure window.

     If N is defined, then capture N events before returning. When N is not defined ginput will loop until the return key RET is pressed.

     The return values X, Y are the coordinates where the mouse was clicked in the units of the current axes.  The return value BUTTON is 1, 2, or 3 for the left, middle, or right button.  If a key is pressed the ASCII value is returned in BUTTON.

     Implementation Note: ginput is intenteded for 2-D plots.  For 3-D plots see the CURRENTPOINT property of the current axes which can be transformed with knowledge of the current view into data units. gtext, waitforbuttonpress

 -- waitforbuttonpress: ()
 -- B =: waitforbuttonpress ()
     Wait for mouse click or key press over the current figure window.

     The return value of B is 0 if a mouse button was pressed or 1 if a key was pressed. waitfor, ginput, kbhit

 -- gtext: (S)
 -- gtext: ({S1, S2, ...})
 -- gtext: ({S1; S2; ...})
 -- gtext: (..., PROP, VAL, ...)
 -- H =: gtext (...)
     Place text on the current figure using the mouse.

     The text is defined by the string S.  If S is a cell string organized as a row vector then each string of the cell array is written to a separate line.  If S is organized as a column vector then one string element of the cell array is placed for every mouse click.

     Optional property/value pairs are passed directly to the underlying text objects.

     The optional return value H is a graphics handle to the created text object(s). ginput, text

More sophisticated user interaction mechanisms can be obtained using the ui* family of functions, see UI Elements.

Test Plotting Functions
-----------------------

The functions sombrero and peaks provide a way to check that plotting is working.  Typing either sombrero or peaks at the Octave prompt should display a three-dimensional plot.

 -- sombrero: ()
 -- sombrero: (N)
 -- Z =: sombrero (...)
 -- [X, Y, Z] =: sombrero (...)
     Plot the familiar 3-D sombrero function.

     The function plotted is

          z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2))

     Called without a return argument, sombrero plots the surface of the above function over the meshgrid [-8,8] using surf.

     If N is a scalar the plot is made with N grid lines. The default value for N is 41.

     When called with output arguments, return the data for the function evaluated over the meshgrid.  This can subsequently be plotted with surf (X, Y, Z).

     peaks, meshgrid, mesh, surf

 -- peaks: ()
 -- peaks: (N)
 -- peaks: (X, Y)
 -- Z =: peaks (...)
 -- [X, Y, Z] =: peaks (...)
     Plot a function with lots of local maxima and minima.

     The function has the form

     f(x,y) = 3*(1-x)^2*exp(-x^2 - (y+1)^2) ...
              - 10*(x/5 - x^3 - y^5)*exp(-x^2-y^2) ...
              - 1/3*exp(-(x+1)^2 - y^2)

     Called without a return argument, peaks plots the surface of the above function using surf.

     If N is a scalar, peaks plots the value of the above function on an N-by-N mesh over the range [-3,3].  The default value for N is 49.

     If N is a vector, then it represents the grid values over which to calculate the function.  If X and Y are specified then the function value is calculated over the specified grid of vertices.

     When called with output arguments, return the data for the function evaluated over the meshgrid.  This can subsequently be plotted with surf (X, Y, Z).

     sombrero, meshgrid, mesh, surf

Graphics Data Structures
========================

Introduction to Graphics Structures
-----------------------------------

The graphics functions use pointers, which are of class graphics_handle, in order to address the data structures which control visual display.  A graphics handle may point to any one of a number of different base object types and these objects are the graphics data structures themselves.  The primitive graphic object types are: figure, axes, line, text, patch, surface, text, image, and light.

Each of these objects has a function by the same name, and, each of these functions returns a graphics handle pointing to an object of the corresponding type.  In addition there are several functions which operate on properties of the graphics objects and which also return handles: the functions plot and plot3 return a handle pointing to an object of type line, the function subplot returns a handle pointing to an object of type axes, the function fill returns a handle pointing to an object of type patch, the functions area, bar, barh, contour, contourf, contour3, surf, mesh, surfc, meshc, errorbar, quiver, quiver3, scatter, scatter3, stair, stem, stem3 each return a handle to a complex data structure as documented in Data Sources.

The graphics objects are arranged in a hierarchy:

1. The root object is returned by groot (historically, equivalent to the handle 0).  In other words, get (groot) returns the properties of the root object.

2. Below the root are figure objects.

3. Below the figure objects are axes or hggroup objects.

4. Below the axes objects are line, text, patch, surface, image, and light objects.

Graphics handles may be distinguished from function handles (see Function Handles) by means of the function ishghandle. ishghandle returns true if its argument is a handle of a graphics object.  In addition, a figure or axes object may be tested using isfigure or isaxes respectively.  To test for a specific type of graphics handle, such as a patch or line object, use isgraphics.  The more specific test functions return true only if the argument is both a graphics handle and of the correct type (figure, axes, specified object type).

The whos function can be used to show the object type of each currently defined graphics handle.  (Note: this is not true today, but it is, I hope, considered an error in whos.  It may be better to have whos just show graphics_handle as the class, and provide a new function which, given a graphics handle, returns its object type.  This could generalize the ishandle() functions and, in fact, replace them.)

The get and set commands are used to obtain and set the values of properties of graphics objects.  In addition, the get command may be used to obtain property names.

For example, the property "type" of the graphics object pointed to by the graphics handle h may be displayed by:

     get (h, "type")

The properties and their current values are returned by get (h) where h is a handle of a graphics object.  If only the names of the allowed properties are wanted they may be displayed by: get (h, "").

Thus, for example:

     h = figure ();
     get (h, "type")
     ans = figure
     get (h, "");
     error: get: ambiguous figure property name ; possible matches:

     __gl_extensions__      dockcontrols           renderer
     __gl_renderer__        doublebuffer           renderermode
     __gl_vendor__          filename               resize
     __gl_version__         graphicssmoothing      resizefcn
     __graphics_toolkit__   handlevisibility       selected
     __guidata__            hittest                selectionhighlight
     __modified__           integerhandle          selectiontype
     __mouse_mode__         interruptible          sizechangedfcn
     __myhandle__           inverthardcopy         tag
     __pan_mode__           keypressfcn            toolbar
     __plot_stream__        keyreleasefcn          type
     __rotate_mode__        menubar                uicontextmenu
     __zoom_mode__          mincolormap            units
     alphamap               name                   userdata
     beingdeleted           nextplot               visible
     busyaction             numbertitle            windowbuttondownfcn
     buttondownfcn          outerposition          windowbuttonmotionfcn
     children               paperorientation       windowbuttonupfcn
     clipping               paperposition          windowkeypressfcn
     closerequestfcn        paperpositionmode      windowkeyreleasefcn
     color                  papersize              windowscrollwheelfcn
     colormap               papertype              windowstyle
     createfcn              paperunits             wvisual
     currentaxes            parent                 wvisualmode
     currentcharacter       pointer                xdisplay
     currentobject          pointershapecdata      xvisual
     currentpoint           pointershapehotspot    xvisualmode
     deletefcn              position

The properties of the root figure may be displayed by: get (groot, "").

The uses of get and set are further explained in get, set.

 -- RES =: isprop (OBJ, "PROP")
     Return true if PROP is a property of the object OBJ.

     OBJ may also be an array of objects in which case RES will be a logical array indicating whether each handle has the property PROP.

     For plotting, OBJ is a handle to a graphics object.  Otherwise, OBJ should be an instance of a class. get, set, ismethod, isobject

Graphics Objects
----------------

The hierarchy of graphics objects was explained above. See Introduction to Graphics Structures.  Here the specific objects are described, and the properties contained in these objects are discussed.  Keep in mind that graphics objects are always referenced by handle.

root figure
     The top level of the hierarchy and the parent of all figure objects. Use groot to obtain the handle of the root graphics object.

figure
     A figure window.

axes
     A set of axes.  This object is a child of a figure object and may be a parent of line, text, image, patch, surface, or light objects.

line
     A line in two or three dimensions.

text
     Text annotations.

image
     A bitmap image.

patch
     A filled polygon, currently limited to two dimensions.

surface
     A three-dimensional surface.

light
     A light object used for lighting effects on patches and surfaces.

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 instead of patch.

 -- axes: ()
 -- axes: (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.

     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. gca, set, get

 -- line: ()
 -- line: (X, Y)
 -- line: (X, Y, PROPERTY, VALUE, ...)
 -- line: (X, Y, Z)
 -- line: (X, Y, Z, PROPERTY, VALUE, ...)
 -- line: (PROPERTY, VALUE, ...)
 -- line: (HAX, ...)
 -- H =: line (...)
     Create line object from X and Y (and possibly Z) and insert in the current axes.

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

     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. 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 caxis 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 caxis 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 Note: The full list of properties is documented at Patch Properties.  Useful patch properties include: "cdata", "edgecolor", "facecolor", "faces", and "facevertexcdata". 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. 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 light and shadow 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).  For patch objects, the normals must be set manually (property "VertexNormals").

     Up to eight light objects are supported per axes.

     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. lighting, material, patch, surface

Handle Functions
................

To determine whether a variable is a graphics object index, or an index to an axes or figure, use the functions ishghandle, isgraphics, isaxes, and isfigure.

 -- ishghandle: (H)
     Return true if H is a graphics handle and false otherwise.

     H may also be a matrix of handles in which case a logical array is returned that is true where the elements of H are graphics handles and false where they are not. isgraphics, isaxes, isfigure, ishandle

 -- isgraphics: (H)
 -- isgraphics: (H, TYPE)
     Return true if H is a graphics handle (of type TYPE) and false otherwise.

     When no TYPE is specified the function is equivalent to ishghandle. ishghandle, ishandle, isaxes, isfigure

 -- ishandle: (H)
     Return true if H is a handle to a graphics or Java object and false otherwise.

     H may also be a matrix of handles in which case a logical array is returned that is true where the elements of H are handles to graphics or Java objects and false where they are not.

     Programming Note: It is often more useful to test for a specific object type.  To determine if a handle belongs to a graphics object use ishghandle or isgraphics.  To determine if a handle belongs to a Java object use isjava. ishghandle, isgraphics, isjava

 -- isaxes: (H)
     Return true if H is an axes graphics handle and false otherwise.

     If H is a matrix then return a logical array which is true where the elements of H are axes graphics handles and false where they are not. isfigure, ishghandle, isgraphics

 -- isfigure: (H)
     Return true if H is a figure graphics handle and false otherwise.

     If H is a matrix then return a logical array which is true where the elements of H are figure graphics handles and false where they are not. isaxes, ishghandle, isgraphics

The function gcf returns an index to the current figure object, or creates one if none exists.  Similarly, gca returns the current axes object, or creates one (and its parent figure object) if none exists.

 -- H =: groot ()
     Return a handle to the root graphics object.

     The root graphics object is the ultimate parent of all graphics objects.

     In addition, the root object contains information about the graphics system as a whole such as the ScreenSize.  Use get (groot) to find out what information is available.

     Defaults for the graphic system as a whole are specified by setting properties of the root graphics object that begin with "Default". For example, to set the default font for all text objects to FreeSans use

          set (groot, "DefaultTextFontName", "FreeSans")

     Default properties can be deleted by using set with the special property value of "remove".  To undo the default font assignment above use

          set (groot, "DefaultTextFontName", "remove")

     Programming Note: The root graphics object is identified by the special handle value of 0.  At some point this unique value may change, but code can be made resistant to future changes by using groot which is guaranteed to always return the root graphics object. gcf, gca, get, set

 -- H =: gcf ()
     Return a handle to the current figure.

     The current figure is the default target for graphics output.  If multiple figures exist, gcf returns the last created figure or the last figure that was clicked on with the mouse.

     If a current figure does not exist, create one and return its handle.  The handle may then be used to examine or set properties of the figure.  For example,

          fplot (@sin, [-10, 10]);
          fig = gcf ();
          set (fig, "numbertitle", "off", "name", "sin plot")

     plots a sine wave, finds the handle of the current figure, and then renames the figure window to describe the contents.

     Note: To find the current figure without creating a new one if it does not exist, query the "CurrentFigure" property of the root graphics object.

          get (groot, "currentfigure");

     gca, gco, gcbf, gcbo, get, set

 -- H =: gca ()
     Return a handle to the current axes object.

     The current axes is the default target for graphics output.  In the case of a figure with multiple axes, gca returns the last created axes or the last axes that was clicked on with the mouse.

     If no current axes object exists, create one and return its handle.  The handle may then be used to examine or set properties of the axes.  For example,

          ax = gca ();
          set (ax, "position", [0.5, 0.5, 0.5, 0.5]);

     creates an empty axes object and then changes its location and size in the figure window.

     Note: To find the current axes without creating a new axes object if it does not exist, query the "CurrentAxes" property of a figure.

          get (gcf, "currentaxes");

     gcf, gco, gcbf, gcbo, get, set

 -- H =: gco ()
 -- H =: gco (FIG)
     Return a handle to the current object of the current figure, or a handle to the current object of the figure with handle FIG.

     The current object of a figure is the object that was last clicked on.  It is stored in the "CurrentObject" property of the target figure.

     If the last mouse click did not occur on any child object of the figure, then the current object is the figure itself.

     If no mouse click occurred in the target figure, this function returns an empty matrix.

     Programming Note: The value returned by this function is not necessarily the same as the one returned by gcbo during callback execution.  An executing callback can be interrupted by another callback and the current object may be changed.

     gcbo, gca, gcf, gcbf, get, set

The get and set functions may be used to examine and set properties for graphics objects.  For example,

     get (groot)
         => ans =
            {
              type = root
              currentfigure = [](0x0)
              children = [](0x0)
              visible = on
              ...
            }

returns a structure containing all the properties of the root figure. As with all functions in Octave, the structure is returned by value, so modifying it will not modify the internal root figure plot object.  To do that, you must use the set function.  Also, note that in this case, the currentfigure property is empty, which indicates that there is no current figure window.

The get function may also be used to find the value of a single property.  For example,

     get (gca (), "xlim")
         => [ 0 1 ]

returns the range of the x-axis for the current axes object in the current figure.

To set graphics object properties, use the set function.  For example,

     set (gca (), "xlim", [-10, 10]);

sets the range of the x-axis for the current axes object in the current figure to [-10, 10].

Default property values can also be queried if the set function is called without a value argument.  When only one argument is given (a graphic handle) then a structure with defaults for all properties of the given object type is returned.  For example,

     set (gca ())

returns a structure containing the default property values for axes objects. If set is called with two arguments (a graphic handle and a property name) then only the defaults for the requested property are returned.

 -- VAL =: get (H)
 -- VAL =: get (H, P)
     Return the value of the named property P from the graphics handle H.

     If P is omitted, return the complete property list for H.

     If H is a vector, return a cell array including the property values or lists respectively. set

 -- set: (H, PROPERTY, VALUE, ...)
 -- set: (H, PROPERTIES, VALUES)
 -- set: (H, PV)
 -- VALUE_LIST =: set (H, PROPERTY)
 -- ALL_VALUE_LIST =: set (H)
     Set named property values for the graphics handle (or vector of graphics handles) H.

     There are three ways to give the property names and values:

       * as a comma separated list of PROPERTY, VALUE pairs

          Here, each PROPERTY is a string containing the property name, each VALUE is a value of the appropriate type for the property.

       * as a cell array of strings PROPERTIES containing property names and a cell array VALUES containing property values.

          In this case, the number of columns of VALUES must match the number of elements in PROPERTIES.  The first column of VALUES contains values for the first entry in PROPERTIES, etc.  The number of rows of VALUES must be 1 or match the number of elements of H.  In the first case, each handle in H will be assigned the same values.  In the latter case, the first handle in H will be assigned the values from the first row of VALUES and so on.

       * as a structure array PV

          Here, the field names of PV represent the property names, and the field values give the property values.  In contrast to the previous case, all elements of PV will be set in all handles in H independent of the dimensions of PV.

     set is also used to query the list of values a named property will take.  CLIST = set (H, "property") will return the list of possible values for "property" in the cell list CLIST. If no output variable is used then the list is formatted and printed to the screen.

     If no property is specified (SLIST = set (H)) then a structure SLIST is returned where the fieldnames are the properties of the object H and the fields are the list of possible values for each property.  If no output variable is used then the list is formatted and printed to the screen.

     For example,

          hf = figure ();
          set (hf, "paperorientation")
          =>  paperorientation:  [ landscape | {portrait} | rotated ]

     shows the paperorientation property can take three values with the default being "portrait". get

 -- PARENT =: ancestor (H, TYPE)
 -- PARENT =: ancestor (H, TYPE, "toplevel")
     Return the first ancestor of handle object H whose type matches TYPE, where TYPE is a character string.

     If TYPE is a cell array of strings, return the first parent whose type matches any of the given type strings.

     If the handle object H itself is of type TYPE, return H.

     If "toplevel" is given as a third argument, return the highest parent in the object hierarchy that matches the condition, instead of the first (nearest) one. findobj, findall, allchild

 -- H =: allchild (HANDLES)
     Find all children, including hidden children, of a graphics object.

     This function is similar to get (h, "children"), but also returns hidden objects (HandleVisibility = "off").

     If HANDLES is a scalar, H will be a vector.  Otherwise, H will be a cell matrix of the same size as HANDLES and each cell will contain a vector of handles. findall, findobj, get, set

 -- findfigs: ()
     Find all visible figures that are currently off the screen and move them onto the screen. allchild, figure, get, set

Figures can be printed or saved in many graphics formats with print and saveas.  Occasionally, however, it may be useful to save the original Octave handle graphic directly so that further modifications can be made such as modifying a title or legend.

This can be accomplished with the following functions by

     fig_struct = hdl2struct (gcf);
     save myplot.fig -struct fig_struct;
     ...
     fig_struct = load ("myplot.fig");
     struct2hdl (fig_struct);

 -- S =: hdl2struct (H)
     Return a structure, S, whose fields describe the properties of the object, and its children, associated with the handle, H.

     The fields of the structure S are "type", "handle", "properties", "children", and "special". struct2hdl, hgsave, findobj

 -- H =: struct2hdl (S)
 -- H =: struct2hdl (S, P)
 -- H =: struct2hdl (S, P, HILEV)
     Construct a graphics handle object H from the structure S.

     The structure must contain the fields "handle", "type", "children", "properties", and "special".

     If the handle of an existing figure or axes is specified, P, the new object will be created as a child of that object.  If no parent handle is provided then a new figure and the necessary children will be constructed using the default values from the root figure.

     A third boolean argument HILEV can be passed to specify whether the function should preserve listeners/callbacks, e.g., for legends or hggroups.  The default is false. hdl2struct, hgload, findobj

 -- HNEW =: copyobj (HORIG)
 -- HNEW =: copyobj (HORIG, HPARENT)
     Construct a copy of the graphic objects associated with the handles HORIG and return new handles HNEW to the new objects.

     If a parent handle HPARENT (root, figure, axes, or hggroup) is specified, the copied object will be created as a child of HPARENT.

     If HORIG is a vector of handles, and HPARENT is a scalar, then each handle in the vector HNEW has its "Parent" property set to HPARENT.  Conversely, if HORIG is a scalar and HPARENT a vector, then each parent object will receive a copy of HORIG.  If HORIG and HPARENT are both vectors with the same number of elements then HNEW(i) will have parent HPARENT(i). struct2hdl, hdl2struct, findobj

Graphics Object Properties
--------------------------

In this Section the graphics object properties are discussed in detail, starting with the root figure properties and continuing through the objects hierarchy.  The documentation about a specific graphics object can be displayed using doc function, e.g., doc ("axes properties") will show Axes Properties.

The allowed values for radio (string) properties can be retrieved programmatically or displayed using the one or two arguments call to set function.  See set.

In the following documentation, default values are enclosed in { }.

Root Figure Properties
......................

The root figure properties are:

     [file plot-rootproperties.texi not included]

Figure Properties
.................

The figure properties are:

     [file plot-figureproperties.texi not included]

Axes Properties
...............

The axes properties are:

     [file plot-axesproperties.texi not included]

Line Properties
...............

The line properties are:

     [file plot-lineproperties.texi not included]

Text Properties
...............

The text properties are:

     [file plot-textproperties.texi not included]

Image Properties
................

The image properties are:

     [file plot-imageproperties.texi not included]

Patch Properties
................

The patch properties are:

     [file plot-patchproperties.texi not included]

Surface Properties
..................

The surface properties are:

     [file plot-surfaceproperties.texi not included]

Light Properties
................

The light properties are:

     [file plot-lightproperties.texi not included]

Uimenu Properties
.................

The uimenu properties are:

     [file plot-uimenuproperties.texi not included]

Uibuttongroup Properties
........................

The uibuttongroup properties are:

     [file plot-uibuttongroupproperties.texi not included]

Uicontextmenu Properties
........................

The uicontextmenu properties are:

     [file plot-uicontextmenuproperties.texi not included]

Uipanel Properties
..................

The uipanel properties are:

     [file plot-uipanelproperties.texi not included]

Uicontrol Properties
....................

The uicontrol properties are:

     [file plot-uicontrolproperties.texi not included]

Uitoolbar Properties
....................

The uitoolbar properties are:

     [file plot-uitoolbarproperties.texi not included]

Uipushtool Properties
.....................

The uipushtool properties are:

     [file plot-uipushtoolproperties.texi not included]

Uitoggletool Properties
.......................

The uitoggletool properties are:

     [file plot-uitoggletoolproperties.texi not included]

Searching Properties
--------------------

 -- H =: findobj ()
 -- H =: findobj (PROP_NAME, PROP_VALUE, ...)
 -- H =: findobj (PROP_NAME, PROP_VALUE, "-LOGICAL_OP", PROP_NAME, PROP_VALUE)
 -- H =: findobj ("-property", PROP_NAME)
 -- H =: findobj ("-regexp", PROP_NAME, PATTERN)
 -- H =: findobj (HLIST, ...)
 -- H =: findobj (HLIST, "flat", ...)
 -- H =: findobj (HLIST, "-depth", D, ...)
     Find graphics objects with specified properties.

     When called without arguments, return all graphic objects beginning with the root object (0) and including all of its descendants.

     The simplest form for narrowing the results is

          findobj (PROP_NAME, PROP_VALUE)

     which returns the handles of all objects which have a property named PROP_NAME that has the value PROP_VALUE.  If multiple property/value pairs are specified then only objects meeting all of the conditions (equivalent to -and) are returned.

     The search can be limited to a particular set of objects and their descendants, by passing a handle or set of handles HLIST as the first argument.

     The depth of the object hierarchy to search can be limited with the "-depth" argument.  An example of searching through only three generations of children is:

          findobj (HLIST, "-depth", 3, PROP_NAME, PROP_VALUE)

     Specifying a depth D of 0 limits the search to the set of objects passed in HLIST.  A depth of 0 is also equivalent to the "flat" argument.  The default depth value is Inf which includes all descendants.

     A specified logical operator may be used between PROP_NAME, PROP_VALUE pairs.  The supported logical operators are: "-and", "-or", "-xor", "-not".  Example code to locate all figure and axes objects is

          findobj ("type", "figure", "-or", "type", "axes")

     Objects may also be matched by comparing a regular expression to the property values, where property values that match regexp (PROP_VALUE, PATTERN) are returned.

     Finally, objects which have a property name can be found with the "-property" option.  For example, code to locate objects with a "meshstyle" property is

          findobj ("-property", "meshstyle")

     Implementation Note: The search only includes objects with visible handles (HandleVisibility = "on").  See findall, to search for all objects including hidden ones. findall, allchild, get, set

 -- H =: findall ()
 -- H =: findall (PROP_NAME, PROP_VALUE, ...)
 -- H =: findall (PROP_NAME, PROP_VALUE, "-LOGICAL_OP", PROP_NAME, PROP_VALUE)
 -- H =: findall ("-property", PROP_NAME)
 -- H =: findall ("-regexp", PROP_NAME, PATTERN)
 -- H =: findall (HLIST, ...)
 -- H =: findall (HLIST, "flat", ...)
 -- H =: findall (HLIST, "-depth", D, ...)
     Find graphics object, including hidden ones, with specified properties.

     The return value H is a list of handles to the found graphic objects.

     findall performs the same search as findobj, but it includes hidden objects (HandleVisibility = "off").  For full documentation, see findobj. findobj, allchild, get, set

Managing Default Properties
---------------------------

Object properties have two classes of default values, factory defaults (the initial values) and user-defined defaults, which may override the factory defaults.

Although default values may be set for any object, they are set in parent objects and apply to child objects, of the specified object type. For example, setting the default color property of line objects to "green", for the root object, will result in all line objects inheriting the color "green" as the default value.

     set (groot, "defaultlinecolor", "green");

sets the default line color for all objects.  The rule for constructing the property name to set a default value is

     default + OBJECT-TYPE + PROPERTY-NAME

This rule can lead to some strange looking names, for example defaultlinelinewidth" specifies the default linewidth property for line objects.

The example above used the root figure object so the default property value will apply to all line objects.  However, default values are hierarchical, so defaults set in a figure objects override those set in the root figure object.  Likewise, defaults set in axes objects override those set in figure or root figure objects.  For example,

     subplot (2, 1, 1);
     set (groot, "defaultlinecolor", "red");
     set (1, "defaultlinecolor", "green");
     set (gca (), "defaultlinecolor", "blue");
     line (1:10, rand (1, 10));
     subplot (2, 1, 2);
     line (1:10, rand (1, 10));
     figure (2)
     line (1:10, rand (1, 10));

produces two figures.  The line in first subplot window of the first figure is blue because it inherits its color from its parent axes object.  The line in the second subplot window of the first figure is green because it inherits its color from its parent figure object.  The line in the second figure window is red because it inherits its color from the global root figure parent object.

To remove a user-defined default setting, set the default property to the value "remove".  For example,

     set (gca (), "defaultlinecolor", "remove");

removes the user-defined default line color setting from the current axes object.  To quickly remove all user-defined defaults use the reset function.

 -- reset: (H)
     Reset the properties of the graphic object H to their default values.

     For figures, the properties "position", "units", "windowstyle", and "paperunits" are not affected. For axes, the properties "position" and "units" are not affected.

     The input H may also be a vector of graphic handles in which case each individual object will be reset. cla, clf, newplot

Getting the "default" property of an object returns a list of user-defined defaults set for the object.  For example,

     get (gca (), "default");

returns a list of user-defined default values for the current axes object.

Factory default values are stored in the root figure object.  The command

     get (groot, "factory");

returns a list of factory defaults.

Advanced Plotting
=================

Colors
------

Colors may be specified as RGB triplets with values ranging from zero to one, or by name.  Recognized color names include "blue", "black", "cyan", "green", "magenta", "red", "white", and "yellow".

Line Styles
-----------

Line styles are specified by the following properties:

linestyle
     May be one of

     "-"
          Solid line.  [default]

     "--"
          Dashed line.

     ":"
          Dotted line.

     "-."
          A dash-dot line.

     "none"
          No line.  Points will still be marked using the current Marker Style.

linewidth
     A number specifying the width of the line.  The default is 1.  A value of 2 is twice as wide as the default, etc.

Marker Styles
-------------

Marker styles are specified by the following properties:

marker
     A character indicating a plot marker to be place at each data point, or "none", meaning no markers should be displayed.

markeredgecolor
     The color of the edge around the marker, or "auto", meaning that the edge color is the same as the face color.  See Colors.

markerfacecolor
     The color of the marker, or "none" to indicate that the marker should not be filled.  See Colors.

markersize
     A number specifying the size of the marker.  The default is 1.  A value of 2 is twice as large as the default, etc.

The colstyle function will parse a plot-style specification and will return the color, line, and marker values that would result.

 -- [STYLE, COLOR, MARKER, MSG] =: colstyle (STYLE)
     Parse the line specification STYLE and return the line style, color, and markers given.

     In the case of an error, the string MSG will return the text of the error.

Callbacks
---------

Callback functions can be associated with graphics objects and triggered after certain events occur.  The basic structure of all callback function is

     function mycallback (hsrc, evt)
       ...
     endfunction

where hsrc is a handle to the source of the callback, and evt gives some event specific data.

The function can be provided as a function handle to a plain Octave function, as an anonymous function, or as a string representing an Octave command.  The latter syntax is not recommended since syntax errors will only occur when the string is evaluated. See Function Handles section.

This can then be associated with an object either at the object's creation, or later with the set function.  For example,

     plot (x, "DeleteFcn", @(h, e) disp ("Window Deleted"))

where at the moment that the plot is deleted, the message "Window Deleted" will be displayed.

Additional user arguments can be passed to callback functions, and will be passed after the two default arguments.  For example:

     plot (x, "DeleteFcn", {@mycallback, "1"})
     ...
     function mycallback (h, evt, arg1)
       fprintf ("Closing plot %d\n", arg1);
     endfunction

Caution: The second argument in callback functions---evt---is only partially implemented in the Qt graphics toolkit:

  * Mouse click events: evt is a class double value: 1 for left, 2 for middle, and 3 for right click.

  * Key press events: evt is a structure with fields Key (string), Character (string), and Modifier (cell array of strings).

  * Other events: evt is a class double empty matrix.

The basic callback functions that are available for all graphics objects are

  * CreateFcn: called at the moment of the objects creation.  It is not called if the object is altered in any way, and so it only makes sense to define this callback in the function call that defines the object.  Callbacks that are added to CreateFcn later with the set function will never be executed.

  * DeleteFcn: called at the moment an object is deleted.

  * ButtonDownFcn: called if a mouse button is pressed while the pointer is over this object.  Note, that the gnuplot interface does not implement this callback.

By default callback functions are queued (they are executed one after the other in the event queue) unless the drawnow, figure, waitfor, getframe, or pause functions are used.  If an executing callback invokes one of those functions, it causes Octave to flush the event queue, which results in the executing callback being interrupted.

It is possible to specify that an object's callbacks should not be interrupted by setting the object's interruptible property to "off".  In this case, Octave decides what to do based on the busyaction property of the interrupting callback object:

queue (the default)
     The interrupting callback is executed after the executing callback has returned.

cancel
     The interrupting callback is discarded.

The interruptible property has no effect when the interrupting callback is a deletefcn, or a figure resizefcn or closerequestfcn. Those callbacks always interrupt the executing callback.

The handle to the object that holds the callback being executed can be obtained with the gcbo function.  The handle to the ancestor figure of this object may be obtained using the gcbf function.

 -- H =: gcbo ()
 -- [H, FIG] =: gcbo ()
     Return a handle to the object whose callback is currently executing.

     If no callback is executing, this function returns the empty matrix.  This handle is obtained from the root object property "CallbackObject".

     When called with a second output argument, return the handle of the figure containing the object whose callback is currently executing.  If no callback is executing the second output is also set to the empty matrix.

     gcbf, gco, gca, gcf, get, set

 -- FIG =: gcbf ()
     Return a handle to the figure containing the object whose callback is currently executing.

     If no callback is executing, this function returns the empty matrix.  The handle returned by this function is the same as the second output argument of gcbo.

     gcbo, gcf, gco, gca, get, set

Callbacks can equally be added to properties with the addlistener function described below.

Application-defined Data
------------------------

Octave has a provision for attaching application-defined data to a graphics handle.  The data can be anything which is meaningful to the application, and will be completely ignored by Octave.

 -- setappdata: (H, NAME, VALUE)
 -- setappdata: (H, NAME1, VALUE1, NAME2, VALUE3, ...)
 -- setappdata: (H, {NAME1, NAME2, ...}, {VALUE1, VALUE2, ...})
     Set the application data NAME to VALUE for the graphics object with handle H.

     H may also be a vector of graphics handles.  If the application data with the specified NAME does not exist, it is created.

     Multiple NAME/VALUE pairs can be specified.  Alternatively, a cell array of NAMES and a corresponding cell array of VALUES can be specified.

     getappdata, isappdata, rmappdata, guidata, get, set, getpref, setpref

 -- VALUE =: getappdata (H, NAME)
 -- APPDATA =: getappdata (H)
     Return the VALUE of the application data NAME for the graphics object with handle H.

     H may also be a vector of graphics handles.  If no second argument NAME is given then getappdata returns a structure, APPDATA, whose fields correspond to the appdata properties.

     setappdata, isappdata, rmappdata, guidata, get, set, getpref, setpref

 -- rmappdata: (H, NAME)
 -- rmappdata: (H, NAME1, NAME2, ...)
     Delete the application data NAME from the graphics object with handle H.

     H may also be a vector of graphics handles.  Multiple application data names may be supplied to delete several properties at once.

     setappdata, getappdata, isappdata

 -- VALID =: isappdata (H, NAME)
     Return true if the named application data, NAME, exists for the graphics object with handle H.

     H may also be a vector of graphics handles. getappdata, setappdata, rmappdata, guidata, get, set, getpref, setpref

Object Groups
-------------

A number of Octave high level plot functions return groups of other graphics objects or they return graphics objects that have their properties linked in such a way that changes to one of the properties results in changes in the others.  A graphic object that groups other objects is an hggroup

 -- hggroup: ()
 -- hggroup: (HAX)
 -- hggroup: (..., PROPERTY, VALUE, ...)
 -- H =: hggroup (...)
     Create handle graphics group object with axes parent HAX.

     If no parent is specified, the group is created in the current axes.

     Multiple property/value pairs may be specified for the hggroup, but they must appear in pairs.

     The optional return value H is a graphics handle to the created hggroup object.

     Programming Note: An hggroup is a way to group base graphics objects such as line objects or patch objects into a single unit which can react appropriately.  For example, the individual lines of a contour plot are collected into a single hggroup so that they can be made visible/invisible with a single command, set (hg_handle, "visible", "off").

     addproperty, addlistener

For example a simple use of a hggroup might be

     x = 0:0.1:10;
     hg = hggroup ();
     plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
     hold on
     plot (x, cos (x), "color", [0, 1, 0], "parent", hg);
     set (hg, "visible", "off");

which groups the two plots into a single object and controls their visibility directly.  The default properties of an hggroup are the same as the set of common properties for the other graphics objects.  Additional properties can be added with the addproperty function.

 -- addproperty: (NAME, H, TYPE)
 -- addproperty: (NAME, H, TYPE, ARG, ...)
     Create a new property named NAME in graphics object H.

     TYPE determines the type of the property to create.  ARGS usually contains the default value of the property, but additional arguments might be given, depending on the type of the property.

     The supported property types are:

     string
          A string property.  ARG contains the default string value.

     any
          An un-typed property.  This kind of property can hold any octave value.  ARGS contains the default value.

     radio
          A string property with a limited set of accepted values.  The first argument must be a string with all accepted values separated by a vertical bar ('|').  The default value can be marked by enclosing it with a '{' '}' pair.  The default value may also be given as an optional second string argument.

     boolean
          A boolean property.  This property type is equivalent to a radio property with "on|off" as accepted values.  ARG contains the default property value.

     double
          A scalar double property.  ARG contains the default value.

     handle
          A handle property.  This kind of property holds the handle of a graphics object.  ARG contains the default handle value. When no default value is given, the property is initialized to the empty matrix.

     data
          A data (matrix) property.  ARG contains the default data value.  When no default value is given, the data is initialized to the empty matrix.

     color
          A color property.  ARG contains the default color value. When no default color is given, the property is set to black. An optional second string argument may be given to specify an additional set of accepted string values (like a radio property).

     TYPE may also be the concatenation of a core object type and a valid property name for that object type.  The property created then has the same characteristics as the referenced property (type, possible values, hidden state...).  This allows one to clone an existing property into the graphics object H.

     Examples:

          addproperty ("my_property", gcf, "string", "a string value");
          addproperty ("my_radio", gcf, "radio", "val_1|val_2|{val_3}");
          addproperty ("my_style", gcf, "linelinestyle", "--");

     addlistener, hggroup

Once a property in added to an hggroup, it is not linked to any other property of either the children of the group, or any other graphics object.  Add so to control the way in which this newly added property is used, the addlistener function is used to define a callback function that is executed when the property is altered.

 -- addlistener: (H, PROP, FCN)
     Register FCN as listener for the property PROP of the graphics object H.

     Property listeners are executed (in order of registration) when the property is set.  The new value is already available when the listeners are executed.

     PROP must be a string naming a valid property in H.

     FCN can be a function handle, a string or a cell array whose first element is a function handle.  If FCN is a function handle, the corresponding function should accept at least 2 arguments, that will be set to the object handle and the empty matrix respectively.  If FCN is a string, it must be any valid octave expression.  If FCN is a cell array, the first element must be a function handle with the same signature as described above.  The next elements of the cell array are passed as additional arguments to the function.

     Example:

          function my_listener (h, dummy, p1)
            fprintf ("my_listener called with p1=%s\n", p1);
          endfunction

          addlistener (gcf, "position", {@my_listener, "my string"})

     dellistener, addproperty, hggroup

 -- dellistener: (H, PROP, FCN)
     Remove the registration of FCN as a listener for the property PROP of the graphics object H.

     The function FCN must be the same variable (not just the same value), as was passed to the original call to addlistener.

     If FCN is not defined then all listener functions of PROP are removed.

     Example:

          function my_listener (h, dummy, p1)
            fprintf ("my_listener called with p1=%s\n", p1);
          endfunction

          c = {@my_listener, "my string"};
          addlistener (gcf, "position", c);
          dellistener (gcf, "position", c);

     addlistener

An example of the use of these two functions might be

     x = 0:0.1:10;
     hg = hggroup ();
     h = plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
     addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle"));
     addlistener (hg, "linestyle", @update_props);
     hold on
     plot (x, cos (x), "color", [0, 1, 0], "parent", hg);

     function update_props (h, d)
       set (get (h, "children"), "linestyle", get (h, "linestyle"));
     endfunction

that adds a linestyle property to the hggroup and propagating any changes its value to the children of the group.  The linkprop function can be used to simplify the above to be

     x = 0:0.1:10;
     hg = hggroup ();
     h1 = plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
     addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle"));
     hold on
     h2 = plot (x, cos (x), "color", [0, 1, 0], "parent", hg);
     hlink = linkprop ([hg, h1, h2], "color");

 -- HLINK =: linkprop (H, "PROP")
 -- HLINK =: linkprop (H, {"PROP1", "PROP2", ...})
     Link graphic object properties, such that a change in one is propagated to the others.

     The input H is a vector of graphic handles to link.

     PROP may be a string when linking a single property, or a cell array of strings for multiple properties.  During the linking process all properties in PROP will initially be set to the values that exist on the first object in the list H.

     The function returns HLINK which is a special object describing the link.  As long as the reference HLINK exists, the link between graphic objects will be active.  This means that HLINK must be preserved in a workspace variable, a global variable, or otherwise stored using a function such as setappdata or guidata.  To unlink properties, execute clear HLINK.

     An example of the use of linkprop is

          x = 0:0.1:10;
          subplot (1,2,1);
          h1 = plot (x, sin (x));
          subplot (1,2,2);
          h2 = plot (x, cos (x));
          hlink = linkprop ([h1, h2], {"color","linestyle"});
          set (h1, "color", "green");
          set (h2, "linestyle", "--");

     linkaxes, addlistener

 -- linkaxes: (HAX)
 -- linkaxes: (HAX, OPTSTR)
     Link the axis limits of 2-D plots such that a change in one is propagated to the others.

     The axes handles to be linked are passed as the first argument HAX.

     The optional second argument is a string which defines which axis limits will be linked.  The possible values for OPTSTR are:

     "x"
          Link x-axes

     "y"
          Link y-axes

     "xy" (default)
          Link both axes

     "off"
          Turn off linking

     If unspecified the default is to link both X and Y axes.

     When linking, the limits from the first axes in HAX are applied to the other axes in the list.  Subsequent changes to any one of the axes will be propagated to the others.

     linkprop, addproperty

These capabilities are used in a number of basic graphics objects. The hggroup objects created by the functions of Octave contain one or more graphics object and are used to:

  * group together multiple graphics objects,

  * create linked properties between different graphics objects, and

  * to hide the nominal user data, from the actual data of the objects.

For example the stem function creates a stem series where each hggroup of the stem series contains two line objects representing the body and head of the stem.  The ydata property of the hggroup of the stem series represents the head of the stem, whereas the body of the stem is between the baseline and this value.  For example

     h = stem (1:4)
     get (h, "xdata")
     => [  1   2   3   4]'
     get (get (h, "children")(1), "xdata")
     => [  1   1 NaN   2   2 NaN   3   3 NaN   4   4 NaN]'

shows the difference between the xdata of the hggroup of a stem series object and the underlying line.

The basic properties of such group objects is that they consist of one or more linked hggroup, and that changes in certain properties of these groups are propagated to other members of the group.  Whereas, certain properties of the members of the group only apply to the current member.

In addition the members of the group can also be linked to other graphics objects through callback functions.  For example the baseline of the bar or stem functions is a line object, whose length and position are automatically adjusted, based on changes to the corresponding hggroup elements.

Data Sources in Object Groups
.............................

All of the group objects contain data source parameters.  There are string parameters that contain an expression that is evaluated to update the relevant data property of the group when the refreshdata function is called.

 -- refreshdata: ()
 -- refreshdata: (H)
 -- refreshdata: (H, WORKSPACE)
     Evaluate any datasource properties of the current figure and update the plot if the corresponding data has changed.

     If the first argument H is a list of graphic handles, then operate on these objects rather than the current figure returned by gcf.

     The optional second argument WORKSPACE can take the following values:

     "base"
          Evaluate the datasource properties in the base workspace.  (default).

     "caller"
          Evaluate the datasource properties in the workspace of the function that called refreshdata.

     An example of the use of refreshdata is:

          x = 0:0.1:10;
          y = sin (x);
          plot (x, y, "ydatasource", "y");
          for i = 1 : 100
            pause (0.1);
            y = sin (x + 0.1*i);
            refreshdata ();
          endfor

Area Series
...........

Area series objects are created by the area function.  Each of the hggroup elements contains a single patch object.  The properties of the area series are

basevalue
     The value where the base of the area plot is drawn.

linewidth
linestyle
     The line width and style of the edge of the patch objects making up the areas.  See Line Styles.

edgecolor
facecolor
     The line and fill color of the patch objects making up the areas. See Colors.

xdata
ydata
     The x and y coordinates of the original columns of the data passed to area prior to the cumulative summation used in the area function.

xdatasource
ydatasource
     Data source variables.

Bar Series
..........

Bar series objects are created by the bar or barh functions.  Each hggroup element contains a single patch object. The properties of the bar series are

showbaseline
baseline
basevalue
     The property showbaseline flags whether the baseline of the bar series is displayed (default is "on").  The handle of the graphics object representing the baseline is given by the baseline property and the y-value of the baseline by the basevalue property.

     Changes to any of these properties are propagated to the other members of the bar series and to the baseline itself.  Equally, changes in the properties of the base line itself are propagated to the members of the corresponding bar series.

barwidth
barlayout
horizontal
     The property barwidth is the width of the bar corresponding to the WIDTH variable passed to bar or BARH.  Whether the bar series is "grouped" or "stacked" is determined by the barlayout property and whether the bars are horizontal or vertical by the horizontal property.

     Changes to any of these property are propagated to the other members of the bar series.

linewidth
linestyle
     The line width and style of the edge of the patch objects making up the bars.  See Line Styles.

edgecolor
facecolor
     The line and fill color of the patch objects making up the bars. See Colors.

xdata
     The nominal x positions of the bars.  Changes in this property and propagated to the other members of the bar series.

ydata
     The y value of the bars in the hggroup.

xdatasource
ydatasource
     Data source variables.

Contour Groups
..............

Contour group objects are created by the contour, contourf, and contour3 functions.  They are also one of the handles returned by the surfc and meshc functions.  The properties of the contour group are

contourmatrix
     A read only property that contains the data return by contourc used to create the contours of the plot.

fill
     A radio property that can have the values "on" or "off" that flags whether the contours to plot are to be filled.

zlevelmode
zlevel
     The radio property zlevelmode can have the values "none", "auto", or "manual".  When its value is "none" there is no z component to the plotted contours.  When its value is "auto" the z value of the plotted contours is at the same value as the contour itself.  If the value is "manual", then the z value at which to plot the contour is determined by the zlevel property.

levellistmode
levellist
levelstepmode
levelstep
     If levellistmode is "manual", then the levels at which to plot the contours is determined by levellist.  If levellistmode is set to "auto", then the distance between contours is determined by levelstep.  If both levellistmode and levelstepmode are set to "auto", then there are assumed to be 10 equal spaced contours.

textlistmode
textlist
textstepmode
textstep
     If textlistmode is "manual", then the labeled contours is determined by textlist.  If textlistmode is set to "auto", then the distance between labeled contours is determined by textstep.  If both textlistmode and textstepmode are set to "auto", then there are assumed to be 10 equal spaced labeled contours.

showtext
     Flag whether the contour labels are shown or not.

labelspacing
     The distance between labels on a single contour in points.

linewidth

linestyle

linecolor
     The properties of the contour lines.  The properties linewidth and linestyle are similar to the corresponding properties for lines.  The property linecolor is a color property (see Colors), that can also have the values of "none" or "auto".  If linecolor is "none", then no contour line is drawn.  If linecolor is "auto" then the line color is determined by the colormap.

xdata
ydata
zdata
     The original x, y, and z data of the contour lines.

xdatasource
ydatasource
zdatasource
     Data source variables.

Error Bar Series
................

Error bar series are created by the errorbar function.  Each hggroup element contains two line objects representing the data and the errorbars separately.  The properties of the error bar series are

color
     The RGB color or color name of the line objects of the error bars. See Colors.

linewidth
linestyle
     The line width and style of the line objects of the error bars.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the error bars.  See Colors.

xdata
ydata
ldata
udata
xldata
xudata
     The original x, y, l, u, xl, xu data of the error bars.

xdatasource
ydatasource
ldatasource
udatasource
xldatasource
xudatasource
     Data source variables.

Line Series
...........

Line series objects are created by the plot  and plot3 functions and are of the type line.  The properties of the line series with the ability to add data sources.

color
     The RGB color or color name of the line objects.  See Colors.

linewidth
linestyle
     The line width and style of the line objects.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers.  See Colors.

xdata
ydata
zdata
     The original x, y and z data.

xdatasource
ydatasource
zdatasource
     Data source variables.

Quiver Group
............

Quiver series objects are created by the quiver or quiver3 functions.  Each hggroup element of the series contains three line objects as children representing the body and head of the arrow, together with a marker as the point of origin of the arrows.  The properties of the quiver series are

autoscale
autoscalefactor
     Flag whether the length of the arrows is scaled or defined directly from the U, V and W data.  If the arrow length is flagged as being scaled by the autoscale property, then the length of the autoscaled arrow is controlled by the autoscalefactor.

maxheadsize
     This property controls the size of the head of the arrows in the quiver series.  The default value is 0.2.

showarrowhead
     Flag whether the arrow heads are displayed in the quiver plot.

color
     The RGB color or color name of the line objects of the quiver.  See Colors.

linewidth
linestyle
     The line width and style of the line objects of the quiver.  See Line Styles.

marker
markerfacecolor
markersize
     The line and fill color of the marker objects at the original of the arrows.  See Colors.

xdata
ydata
zdata
     The origins of the values of the vector field.

udata
vdata
wdata
     The values of the vector field to plot.

xdatasource
ydatasource
zdatasource
udatasource
vdatasource
wdatasource
     Data source variables.

Scatter Group
.............

Scatter series objects are created by the scatter or scatter3 functions.  A single hggroup element contains as many children as there are points in the scatter plot, with each child representing one of the points. The properties of the stem series are

linewidth
     The line width of the line objects of the points.  See Line Styles.

marker
markeredgecolor
markerfacecolor
     The line and fill color of the markers of the points.  See Colors.

xdata
ydata
zdata
     The original x, y and z data of the stems.

cdata
     The color data for the points of the plot.  Each point can have a separate color, or a unique color can be specified.

sizedata
     The size data for the points of the plot.  Each point can its own size or a unique size can be specified.

xdatasource
ydatasource
zdatasource
cdatasource
sizedatasource
     Data source variables.

Stair Group
...........

Stair series objects are created by the stair function.  Each hggroup element of the series contains a single line object as a child representing the stair.  The properties of the stair series are

color
     The RGB color or color name of the line objects of the stairs.  See Colors.

linewidth
linestyle
     The line width and style of the line objects of the stairs.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the stairs.  See Colors.

xdata
ydata
     The original x and y data of the stairs.

xdatasource
ydatasource
     Data source variables.

Stem Series
...........

Stem series objects are created by the stem or stem3 functions.  Each hggroup element contains a single line object as a child representing the stems.  The properties of the stem series are

showbaseline
baseline
basevalue
     The property showbaseline flags whether the baseline of the stem series is displayed (default is "on").  The handle of the graphics object representing the baseline is given by the baseline property and the y-value (or z-value for stem3) of the baseline by the basevalue property.

     Changes to any of these property are propagated to the other members of the stem series and to the baseline itself.  Equally changes in the properties of the base line itself are propagated to the members of the corresponding stem series.

color
     The RGB color or color name of the line objects of the stems.  See Colors.

linewidth
linestyle
     The line width and style of the line objects of the stems.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the stems.  See Colors.

xdata
ydata
zdata
     The original x, y and z data of the stems.

xdatasource
ydatasource
zdatasource
     Data source variables.

Surface Group
.............

Surface group objects are created by the surf or mesh functions, but are equally one of the handles returned by the surfc or meshc functions.  The surface group is of the type surface.

The properties of the surface group are

edgecolor

facecolor
     The RGB color or color name of the edges or faces of the surface. See Colors.

linewidth
linestyle
     The line width and style of the lines on the surface.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the surface.  See Colors.

xdata
ydata
zdata
cdata
     The original x, y, z and c data.

xdatasource
ydatasource
zdatasource
cdatasource
     Data source variables.

Transform Groups
----------------

 -- H =: hgtransform ()
 -- H =: hgtransform (PROPERTY, VALUE, ...)
 -- H =: hgtransform (HAX, ...)

     Create a graphics transform object.

     FIXME: Need to write documentation. FIXME: Add 'makehgtform' to seealso list when it is implemented. hggroup

Graphics Toolkits
-----------------

 -- NAME =: graphics_toolkit ()
 -- NAME =: graphics_toolkit (HLIST)
 -- graphics_toolkit: (NAME)
 -- graphics_toolkit: (HLIST, NAME)
     Query or set the default graphics toolkit which is assigned to new figures.

     With no inputs, return the current default graphics toolkit.  If the input is a list of figure graphic handles, HLIST, then return the name of the graphics toolkit in use for each figure.

     When called with a single input NAME set the default graphics toolkit to NAME.  If the toolkit is not already loaded, it is initialized by calling the function __init_NAME__.  If the first input is a list of figure handles, HLIST, then the graphics toolkit is set to NAME for these figures only.

     available_graphics_toolkits

 -- available_graphics_toolkits: ()
     Return a cell array of registered graphics toolkits. graphics_toolkit, register_graphics_toolkit

 -- loaded_graphics_toolkits: ()
     Return a cell array of the currently loaded graphics toolkits. available_graphics_toolkits

 -- register_graphics_toolkit: (TOOLKIT)
     List TOOLKIT as an available graphics toolkit. available_graphics_toolkits

Customizing Toolkit Behavior
............................

The specific behavior of the backend toolkit may be modified using the following utility functions.  Note: Not all functions apply to every graphics toolkit.

 -- [PROG, ARGS] =: gnuplot_binary ()
 -- [OLD_PROG, OLD_ARGS] =: gnuplot_binary (NEW_PROG)
 -- [OLD_PROG, OLD_ARGS] =: gnuplot_binary (NEW_PROG, ARG1, ...)
     Query or set the name of the program invoked by the plot command when the graphics toolkit is set to "gnuplot".

     Additional arguments to pass to the external plotting program may also be given.  The default value is "gnuplot" with no additional arguments. See Installation. graphics_toolkit

Hardware vs. Software Rendering
...............................

On Windows platforms, Octave uses software rendering for the OpenGL graphics toolkits ("qt" and "fltk") by default.  This is done to avoid rendering and printing issues due to imperfect OpenGL driver implementations for diverse graphic cards from different vendors.  As a down-side, software rendering might be considerably slower than hardware accelerated rendering.  To permanently switch back to hardware accelerated rendering with your graphic card drivers, rename the following file while Octave is closed:

OCTAVE-HOME\bin\opengl32.dll

where OCTAVE-HOME is the directory in which Octave is installed (the default is C:\Octave\Octave-VERSION).