File: plot.texi

package info (click to toggle)
octave3.2 3.2.4-8
links: PTS, VCS
area: main
in suites: squeeze
size: 62,936 kB
ctags: 37,353
sloc: cpp: 219,497; fortran: 116,336; ansic: 10,264; sh: 5,508; makefile: 4,245; lex: 3,573; yacc: 3,062; objc: 2,042; lisp: 1,692; awk: 860; perl: 844
file content (5277 lines) | stat: -rw-r--r-- 175,717 bytes
@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996, 1997, 1999, 2000, 2002, 2003, 2004, 2005,
@c               2006, 2007, 2008, 2009 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Plotting
@chapter Plotting
@cindex plotting
@cindex graphics

@menu
* Plotting Basics::
* Advanced Plotting::
@end menu

@node Plotting Basics
@section Plotting Basics

Octave makes it easy to create many different types of two- and
three-dimensional plots using a few high-level functions.

If you need finer control over graphics, see @ref{Advanced Plotting}.

@menu
* Two-Dimensional Plots::       
* Three-Dimensional Plotting::  
* Plot Annotations::            
* Multiple Plots on One Page::  
* Multiple Plot Windows::       
* Printing Plots::              
* Interacting with plots::
* Test Plotting Functions::     
@end menu

@node Two-Dimensional Plots
@subsection Two-Dimensional Plots

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

@example
@group
x = -10:0.1:10;
plot (x, sin (x));
@end group
@end example

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

@float Figure,fig:plot
@center @image{plot,4in}
@caption{Simple Two-Dimensional Plot.}
@end float

@c ./plot/plot.m
@anchor{doc-plot}
@deftypefn {Function File} {} plot (@var{y})
@deftypefnx {Function File} {} plot (@var{x}, @var{y})
@deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} plot (@var{h}, @dots{})
Produces two-dimensional plots.  Many different combinations of
arguments are possible.  The simplest form is

@example
plot (@var{y})
@end example

@noindent
where the argument is taken as the set of @var{y} coordinates and the
@var{x} coordinates are taken to be the indices of the elements,
starting with 1.

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

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

@example
plot (@var{y}, @var{property}, @var{value}, @dots{})
@end example

@noindent
or

@example
plot (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@end example

@noindent
or

@example
plot (@var{x}, @var{y}, @var{fmt}, @dots{})
@end example

@noindent
and so on.  Any number of argument sets may appear.  The @var{x} and
@var{y} values are interpreted as follows:

@itemize @bullet
@item
If a single data argument is supplied, it is taken as the set of @var{y}
coordinates and the @var{x} coordinates are taken to be the indices of
the elements, starting with 1.

@item
If the @var{x} is a vector and @var{y} is a matrix, then
the columns (or rows) of @var{y} are plotted versus @var{x}.
(using whichever combination matches, with columns tried first.)

@item
If the @var{x} is a matrix and @var{y} is a vector,
@var{y} is plotted versus the columns (or rows) of @var{x}.
(using whichever combination matches, with columns tried first.)

@item
If both arguments are vectors, the elements of @var{y} are plotted versus
the elements of @var{x}.

@item
If both arguments are matrices, the columns of @var{y} are plotted
versus the columns of @var{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.

If both arguments are scalars, a single point is plotted.
@end itemize

Multiple property-value pairs may be specified, but they must appear
in pairs.  These arguments are applied to the lines drawn by
@code{plot}.

If the @var{fmt} argument is supplied, it is interpreted as
follows.  If @var{fmt} is missing, the default gnuplot line style
is assumed.

@table @samp
@item -
Set lines plot style (default).

@item .
Set dots plot style.

@item @var{n}
Interpreted as the plot color if @var{n} is an integer in the range 1 to
6.

@item @var{nm}
If @var{nm} is a two digit integer and @var{m} is an integer in the
range 1 to 6, @var{m} is interpreted as the point style.  This is only
valid in combination with the @code{@@} or @code{-@@} specifiers.

@item @var{c}
If @var{c} is one of @code{"k"} (black), @code{"r"} (red), @code{"g"}
(green), @code{"b"} (blue), @code{"m"} (magenta), @code{"c"} (cyan),
or @code{"w"} (white), it is interpreted as the line plot color.

@item ";title;"
Here @code{"title"} is the label for the key.

@item +
@itemx *
@itemx o
@itemx x
@itemx ^
Used in combination with the points or linespoints styles, set the point
style.
@end table

The @var{fmt} argument may also be used to assign key titles.
To do so, include the desired title between semi-colons after the
formatting sequence described above, e.g., "+3;Key Title;"
Note that the last semi-colon is required and will generate an error if
it is left out.

Here are some plot examples:

@example
plot (x, y, "@@12", x, y2, x, y3, "4", x, y4, "+")
@end example

This command will plot @code{y} with points of type 2 (displayed as
@samp{+}) and color 1 (red), @code{y2} with lines, @code{y3} with lines of
color 4 (magenta) and @code{y4} with points displayed as @samp{+}.

@example
plot (b, "*", "markersize", 3)
@end example

This command will plot the data in the variable @code{b},
with points displayed as @samp{*} with a marker size of 3.

@example
@group
t = 0:0.1:6.3;
plot (t, cos(t), "-;cos(t);", t, sin(t), "+3;sin(t);");
@end group
@end example

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

If the first argument is an axis handle, then plot into these axes, 
rather than the current axis handle returned by @code{gca}. 
@seealso{@ref{doc-semilogx,,semilogx}, @ref{doc-semilogy,,semilogy}, @ref{doc-loglog,,loglog}, @ref{doc-polar,,polar}, @ref{doc-mesh,,mesh}, @ref{doc-contour,,contour}, @ref{doc-bar,,bar}, @ref{doc-stairs,,stairs}, @ref{doc-errorbar,,errorbar}, @ref{doc-xlabel,,xlabel}, @ref{doc-ylabel,,ylabel}, @ref{doc-title,,title}, @ref{doc-print,,print}}
@end deftypefn


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

@c ./plot/plotyy.m
@anchor{doc-plotyy}
@deftypefn {Function File} {} plotyy (@var{x1}, @var{y1}, @var{x2}, @var{y2})
@deftypefnx {Function File} {} plotyy (@dots{}, @var{fun})
@deftypefnx {Function File} {} plotyy (@dots{}, @var{fun1}, @var{fun2})
@deftypefnx {Function File} {} plotyy (@var{h}, @dots{})
@deftypefnx {Function File} {[@var{ax}, @var{h1}, @var{h2}] =} plotyy (@dots{})
Plots two sets of data with independent y-axes.  The arguments @var{x1} and
@var{y1} define the arguments for the first plot and @var{x1} and @var{y2}
for the second. 

By default the arguments are evaluated with 
@code{feval (@@plot, @var{x}, @var{y})}.  However the type of plot can be
modified with the @var{fun} argument, in which case the plots are
generated by @code{feval (@var{fun}, @var{x}, @var{y})}.  @var{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 @var{fun1} and @var{fun2}.

If given, @var{h} defines the principal axis in which to plot the @var{x1}
and @var{y1} data.  The return value @var{ax} is a two element vector with
the axis handles of the two plots.  @var{h1} and @var{h2} are handles to
the objects generated by the plot commands.

@example
@group
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");
@end group
@end example
@end deftypefn


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

@c ./plot/semilogx.m
@anchor{doc-semilogx}
@deftypefn {Function File} {} semilogx (@var{args})
Produce a two-dimensional plot using a log scale for the @var{x}
axis.  See the description of @code{plot} for a description of the
arguments that @code{semilogx} will accept.
@seealso{@ref{doc-plot,,plot}, @ref{doc-semilogy,,semilogy}, @ref{doc-loglog,,loglog}}
@end deftypefn


@c ./plot/semilogy.m
@anchor{doc-semilogy}
@deftypefn {Function File} {} semilogy (@var{args})
Produce a two-dimensional plot using a log scale for the @var{y}
axis.  See the description of @code{plot} for a description of the
arguments that @code{semilogy} will accept.
@seealso{@ref{doc-plot,,plot}, @ref{doc-semilogx,,semilogx}, @ref{doc-loglog,,loglog}}
@end deftypefn


@c ./plot/loglog.m
@anchor{doc-loglog}
@deftypefn {Function File} {} loglog (@var{args})
Produce a two-dimensional plot using log scales for both axes.  See
the description of @code{plot} for a description of the arguments
that @code{loglog} will accept.
@seealso{@ref{doc-plot,,plot}, @ref{doc-semilogx,,semilogx}, @ref{doc-semilogy,,semilogy}}
@end deftypefn


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

@example
@group
hist (randn (10000, 1), 30);
@end group
@end example

@noindent
produces the histogram of 10,000 normally distributed random numbers
shown in @ref{fig:hist}.

@float Figure,fig:hist
@center @image{hist,4in}
@caption{Histogram.}
@end float

@c ./plot/bar.m
@anchor{doc-bar}
@deftypefn {Function File} {} bar (@var{x}, @var{y})
@deftypefnx {Function File} {} bar (@var{y})
@deftypefnx {Function File} {} bar (@var{x}, @var{y}, @var{w})
@deftypefnx {Function File} {} bar (@var{x}, @var{y}, @var{w}, @var{style})
@deftypefnx {Function File} {@var{h} =} bar (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} bar (@var{h}, @dots{})
Produce a 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 taken to be the indices of the elements.

The default width of 0.8 for the bars can be changed using @var{w}. 

If @var{y} is a matrix, then each column of @var{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 @var{style}
argument, which can take the values @code{"grouped"} (the default),
or @code{"stacked"}.

The optional return value @var{h} provides a handle to the "bar series"
object with one handle per column of the variable @var{y}.  This
series allows common elements of the group of bar series objects to
be changed in a single bar series and the same properties are changed
in the other "bar series".  For example

@example
@group
h = bar (rand (5, 10));
set (h(1), "basevalue", 0.5);
@end group
@end example

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

The optional input handle @var{h} allows an axis handle to be passed.
Properties of the patch graphics object can be changed using
@var{prop}, @var{val} pairs.

@seealso{@ref{doc-barh,,barh}, @ref{doc-plot,,plot}} 
@end deftypefn


@c ./plot/barh.m
@anchor{doc-barh}
@deftypefn {Function File} {} barh (@var{x}, @var{y})
@deftypefnx {Function File} {} barh (@var{y})
@deftypefnx {Function File} {} barh (@var{x}, @var{y}, @var{w})
@deftypefnx {Function File} {} barh (@var{x}, @var{y}, @var{w}, @var{style})
@deftypefnx {Function File} {@var{h} =} barh (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} barh (@var{h}, @dots{})
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 taken to be the indices of the elements.

The default width of 0.8 for the bars can be changed using @var{w}. 

If @var{y} is a matrix, then each column of @var{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 @var{style}
argument, which can take the values @code{"grouped"} (the default),
or @code{"stacked"}.

The optional return value @var{h} provides a handle to the bar series
object.  See @code{bar} for a description of the use of the bar series.

The optional input handle @var{h} allows an axis handle to be passed.
Properties of the patch graphics object can be changed using
@var{prop}, @var{val} pairs.

@seealso{@ref{doc-bar,,bar}, @ref{doc-plot,,plot}}
@end deftypefn


@c ./plot/hist.m
@anchor{doc-hist}
@deftypefn {Function File} {} hist (@var{y}, @var{x}, @var{norm})
Produce histogram counts or plots.

With one vector input argument, plot a histogram of the values with
10 bins.  The range of the histogram bins is determined by the range
of the data.  With one matrix input argument, plot a histogram where
each bin contains a bar per input column.

Given a second scalar argument, use that as the number of bins.

Given a second vector argument, use that as the centers of the bins,
with the width of the bins determined from the adjacent values in
the vector.

If third argument is provided, the histogram is normalized such that
the sum of the bars is equal to @var{norm}.

Extreme values are lumped in the first and last bins.

With two output arguments, produce the values @var{nn} and @var{xx} such
that @code{bar (@var{xx}, @var{nn})} will plot the histogram.
@seealso{@ref{doc-bar,,bar}}
@end deftypefn


@c ./plot/stairs.m
@anchor{doc-stairs}
@deftypefn {Function File} {} stairs (@var{x}, @var{y})
@deftypefnx {Function File} {} stairs (@dots{}, @var{style})
@deftypefnx {Function File} {} stairs (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} stairs (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} stairs (@dots{})
Produce a stairstep plot.  The arguments 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.

If two output arguments are specified, the data are generated but
not plotted.  For example,

@example
stairs (x, y);
@end example

@noindent
and

@example
@group
[xs, ys] = stairs (x, y);
plot (xs, ys);
@end group
@end example

@noindent
are equivalent.
@seealso{@ref{doc-plot,,plot}, @ref{doc-semilogx,,semilogx}, @ref{doc-semilogy,,semilogy}, @ref{doc-loglog,,loglog}, @ref{doc-polar,,polar}, @ref{doc-mesh,,mesh}, @ref{doc-contour,,contour}, @ref{doc-bar,,bar}, @ref{doc-xlabel,,xlabel}, @ref{doc-ylabel,,ylabel}, @ref{doc-title,,title}}
@end deftypefn


@c ./plot/stem.m
@anchor{doc-stem}
@deftypefn {Function File} {@var{h} =} stem (@var{x}, @var{y}, @var{linespec})
@deftypefnx {Function File} {@var{h} =} stem (@dots{}, "filled")
Plot a stem graph from two vectors of x-y data.  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 @var{y} is a matrix, then each column of the matrix is plotted as
a separate stem graph.  In this case @var{x} can either be a vector,
the same length as the number of rows in @var{y}, or it can be a
matrix of the same size as @var{y}.

The default color is @code{"r"} (red).  The default line style is
@code{"-"} and the default marker is @code{"o"}.  The line style can
be altered by the @code{linespec} argument in the same manner as the
@code{plot} command.  For example

@example
@group
x = 1:10;
y = ones (1, length (x))*2.*x;
stem (x, y, "b");
@end group
@end example

@noindent
plots 10 stems with heights from 2 to 20 in blue;

The return value of @code{stem} is a vector if "stem series" graphics
handles, with one handle per column of the variable @var{y}.  This
handle regroups the elements of the stem graph together as the
children of the "stem series" handle, allowing them to be altered
together.  For example

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

@noindent
changes the color of the second "stem series"  and moves the base line
of the first.
@seealso{@ref{doc-bar,,bar}, @ref{doc-barh,,barh}, @ref{doc-plot,,plot}}
@end deftypefn


@c ./plot/stem3.m
@anchor{doc-stem3}
@deftypefn {Function File} {@var{h} =} stem3 (@var{x}, @var{y}, @var{z}, @var{linespec})
Plot a three-dimensional stem graph and return the handles of the line
and marker objects used to draw the stems as "stem series" object.
The default color is @code{"r"} (red).  The default line style is
@code{"-"} and the default marker is @code{"o"}.

For example,
@example
@group
theta = 0:0.2:6; 
stem3 (cos (theta), sin (theta), theta) 
@end group
@end example

@noindent
plots 31 stems with heights from 0 to 6 lying on a circle.  Color 
definitions with rgb-triples are not valid!
@seealso{@ref{doc-bar,,bar}, @ref{doc-barh,,barh}, @ref{doc-stem,,stem}, @ref{doc-plot,,plot}}
@end deftypefn


@c ./plot/scatter.m
@anchor{doc-scatter}
@deftypefn {Function File} {} scatter (@var{x}, @var{y}, @var{s}, @var{c})
@deftypefnx {Function File} {} scatter (@dots{}, 'filled')
@deftypefnx {Function File} {} scatter (@dots{}, @var{style})
@deftypefnx {Function File} {} scatter (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} scatter (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} scatter (@dots{})

Plot a scatter plot of the data.  A marker is plotted at each point 
defined by the points in the vectors @var{x} and @var{y}.  The size of
the markers used is determined by the @var{s}, which can be a scalar, 
a vector of the same length of @var{x} and @var{y}.  If @var{s} is not 
given or is an empty matrix, then the default value of 8 points is used.

The color of the markers is determined by @var{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 @var{x} that gives
a scaled index into the current colormap, or a @var{n}-by-3 matrix defining
the colors of each of the markers individually.

The marker to use can be changed with the @var{style} argument, that is a 
string defining a marker in the same manner as the @code{plot} command. 
If the argument 'filled' is given then the markers as filled.  All 
additional arguments are passed to the underlying patch command.

The optional return value @var{h} provides a handle to the patch object

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

@seealso{@ref{doc-plot,,plot}, @ref{doc-patch,,patch}, @ref{doc-scatter3,,scatter3}}
@end deftypefn


@c ./plot/scatter3.m
@anchor{doc-scatter3}
@deftypefn {Function File} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}, @var{c})
@deftypefnx {Function File} {} scatter3 (@dots{}, 'filled')
@deftypefnx {Function File} {} scatter3 (@dots{}, @var{style})
@deftypefnx {Function File} {} scatter3 (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} scatter3 (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} scatter3 (@dots{})

Plot a scatter plot of the data in 3D.  A marker is plotted at each point 
defined by the points in the vectors @var{x}, @var{y} and @var{z}.  The size
of the markers used is determined by @var{s}, which can be a scalar or
a vector of the same length of @var{x}, @var{y} and @var{z}.  If @var{s} is
not given or is an empty matrix, then the default value of 8 points is used.

The color of the markers is determined by @var{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 @var{x} that gives
a scaled index into the current colormap, or a @var{n}-by-3 matrix defining
the colors of each of the markers individually.

The marker to use can be changed with the @var{style} argument, that is a 
string defining a marker in the same manner as the @code{plot} command. 
If the argument 'filled' is given then the markers as filled.  All 
additional arguments are passed to the underlying patch command.

The optional return value @var{h} provides a handle to the patch object

@example
@group
[x, y, z] = peaks (20);
scatter3 (x(:), y(:), z(:), [], z(:));
@end group
@end example

@seealso{@ref{doc-plot,,plot}, @ref{doc-patch,,patch}, @ref{doc-scatter,,scatter}}
@end deftypefn


@c ./plot/plotmatrix.m
@anchor{doc-plotmatrix}
@deftypefn {Function File} {} plotmatrix (@var{x}, @var{y})
@deftypefnx {Function File} {} plotmatrix (@var{x})
@deftypefnx {Function File} {} plotmatrix (@dots{}, @var{style})
@deftypefnx {Function File} {} plotmatrix (@var{h}, @dots{})
@deftypefnx {Function File} {[@var{h}, @var{ax}, @var{bigax}, @var{p}, @var{pax}] =} plotmatrix (@dots{})
Scatter plot of the columns of one matrix against another.  Given the
arguments @var{x} and @var{y}, that have a matching number of rows,
@code{plotmatrix} plots a set of axes corresponding to

@example
plot (@var{x} (:, i), @var{y} (:, j)
@end example

Given a single argument @var{x}, then this is equivalent to 

@example
plotmatrix (@var{x}, @var{x})
@end example

@noindent
except that the diagonal of the set of axes will be replaced with the
histogram @code{hist (@var{x} (:, i))}.

The marker to use can be changed with the @var{style} argument, that is a 
string defining a marker in the same manner as the @code{plot}
command.  If a leading axes handle @var{h} is passed to
@code{plotmatrix}, then this axis will be used for the plot.

The optional return value @var{h} provides handles to the individual
graphics objects in the scatter plots, whereas @var{ax} returns the
handles to the scatter plot axis objects.  @var{bigax} is a hidden
axis object that surrounds the other axes, such that the commands 
@code{xlabel}, @code{title}, etc., will be associated with this hidden
axis.  Finally @var{p} returns the graphics objects associated with
the histogram and @var{pax} the corresponding axes objects.

@example
@group
plotmatrix (randn (100, 3), 'g+')
@end group
@end example

@end deftypefn


@c ./plot/pareto.m
@anchor{doc-pareto}
@deftypefn {Function File} {} pareto (@var{x})
@deftypefnx {Function File} {} pareto (@var{x}, @var{y})
@deftypefnx {Function File} {} pareto (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} pareto (@dots{})
Draw a Pareto chart, also called ABC chart.  A Pareto chart is a bar graph 
used to arrange 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 
order from left to right along the abscissa.

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, so for quality improvement the first few (as presented on the 
diagram) contributing causes 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.

The data are passed as @var{x} and the abscissa as @var{y}.  If @var{y} is
absent, then the abscissa are assumed to be @code{1 : length (@var{x})}.
@var{y} can be a string array, a cell array of strings or a numerical
vector.

An example of the use of @code{pareto} is

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


@c ./plot/rose.m
@anchor{doc-rose}
@deftypefn {Function File} {} rose (@var{th}, @var{r})
@deftypefnx {Function File} {} rose (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} rose (@dots{})
@deftypefnx {Function File} {[@var{r}, @var{th}] =} rose (@dots{})

Plot an angular histogram.  With one vector argument @var{th}, plots the
histogram with 20 angular bins.  If @var{th} is a matrix, then each column
of @var{th} produces a separate histogram.

If @var{r} is given and is a scalar, then the histogram is produced with
@var{r} bins.  If @var{r} is a vector, then the center of each bin are 
defined by the values of @var{r}.

The optional return value @var{h} provides a list of handles to the 
the parts of the vector field (body, arrow and marker).

If two output arguments are requested, then rather than plotting the 
histogram, the polar vectors necessary to plot the histogram are 
returned.

@example
@group
[r, t] = rose ([2*randn(1e5,1), pi + 2 * randn(1e5,1)]);
polar (r, t);
@end group
@end example


@seealso{@ref{doc-plot,,plot}, @ref{doc-compass,,compass}, @ref{doc-polar,,polar}, @ref{doc-hist,,hist}}
@end deftypefn


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

@c ./plot/contour.m
@anchor{doc-contour}
@deftypefn {Function File} {} contour (@var{z})
@deftypefnx {Function File} {} contour (@var{z}, @var{vn})
@deftypefnx {Function File} {} contour (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} contour (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {Function File} {} contour (@dots{}, @var{style})
@deftypefnx {Function File} {} contour (@var{h}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contour (@dots{})
Plot level curves (contour lines) of the matrix @var{z}, using the
contour matrix @var{c} computed by @code{contourc} from the same
arguments; see the latter for their interpretation.  The set of
contour levels, @var{c}, is only returned if requested.  For example:

@example
@group
x = 0:2;
y = x;
z = x' * y;
contour (x, y, z, 2:3)
@end group
@end example

The style to use for the plot can be defined with a line style @var{style}
in a similar manner to the line styles used with the @code{plot} command.
Any markers defined by @var{style} are ignored.

The optional input and output argument @var{h} allows an axis handle to 
be passed to @code{contour} and the handles to the contour objects to be
returned.
@seealso{@ref{doc-contourc,,contourc}, @ref{doc-patch,,patch}, @ref{doc-plot,,plot}}
@end deftypefn


@c ./plot/contourf.m
@anchor{doc-contourf}
@deftypefn {Function File} {[@var{c}, @var{h}] =} contourf (@var{x}, @var{y}, @var{z}, @var{lvl})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{x}, @var{y}, @var{z}, @var{n})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{z}, @var{n})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{z}, @var{lvl})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{z})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{ax}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@dots{}, @var{"property"}, @var{val})
Compute and plot filled contours of the matrix @var{z}.
Parameters @var{x}, @var{y} and @var{n} or @var{lvl} are optional.

The return value @var{c} is a 2xn matrix containing the contour lines
as described in the help to the contourc function.

The return value @var{h} is handle-vector to the patch objects creating
the filled contours.

If @var{x} and @var{y} are omitted they are taken as the row/column
index of @var{z}.  @var{n} is a scalar denoting the number of lines
to compute.  Alternatively @var{lvl} is a vector containing the
contour levels.  If only one value (e.g., lvl0) is wanted, set
@var{lvl} to [lvl0, lvl0].  If both @var{n} or @var{lvl} are omitted
a default value of 10 contour level is assumed.

If provided, the filled contours are added to the axes object
@var{ax} instead of the current axis.

The following example plots filled contours of the @code{peaks}
function.
@example
@group
[x, y, z] = peaks (50);
contourf (x, y, z, -7:9)
@end group
@end example
@seealso{@ref{doc-contour,,contour}, @ref{doc-contourc,,contourc}, @ref{doc-patch,,patch}}
@end deftypefn


@c ./plot/contourc.m
@anchor{doc-contourc}
@deftypefn {Function File} {[@var{c}, @var{lev}] =}  contourc (@var{x}, @var{y}, @var{z}, @var{vn})
Compute isolines (contour lines) of the matrix @var{z}. 
Parameters @var{x}, @var{y} and @var{vn} are optional.

The return value @var{lev} is a vector of the contour levels.
The return value @var{c} is a 2 by @var{n} matrix containing the
contour lines in the following format

@example
@group
@var{c} = [lev1, x1, x2, @dots{}, levn, x1, x2, @dots{} 
     len1, y1, y2, @dots{}, lenn, y1, y2, @dots{}]
@end group
@end example

@noindent
in which contour line @var{n} has a level (height) of @var{levn} and
length of @var{lenn}.

If @var{x} and @var{y} are omitted they are taken as the row/column 
index of @var{z}.  @var{vn} is either a scalar denoting the number of lines 
to compute or a vector containing the values of the lines.  If only one 
value is wanted, set @code{@var{vn} = [val, val]};
If @var{vn} is omitted it defaults to 10.

For example,
@example
@group
x = 0:2;
y = x;
z = x' * y;
contourc (x, y, z, 2:3)
     @result{}   2.0000   2.0000   1.0000   3.0000   1.5000   2.0000
     2.0000   1.0000   2.0000   2.0000   2.0000   1.5000

@end group
@end example
@seealso{@ref{doc-contour,,contour}}
@end deftypefn


@c ./plot/contour3.m
@anchor{doc-contour3}
@deftypefn {Function File} {} contour3 (@var{z})
@deftypefnx {Function File} {} contour3 (@var{z}, @var{vn})
@deftypefnx {Function File} {} contour3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} contour3 (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {Function File} {} contour3 (@dots{}, @var{style})
@deftypefnx {Function File} {} contour3 (@var{h}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contour3 (@dots{})
Plot level curves (contour lines) of the matrix @var{z}, using the
contour matrix @var{c} computed by @code{contourc} from the same
arguments; see the latter for their interpretation.  The contours are
plotted at the Z level corresponding to their contour.  The set of
contour levels, @var{c}, is only returned if requested.  For example:

@example
@group
contour3 (peaks (19));
hold on
surface (peaks (19), "facecolor", "none", "EdgeColor", "black")
colormap hot
@end group
@end example

The style to use for the plot can be defined with a line style @var{style}
in a similar manner to the line styles used with the @code{plot} command.
Any markers defined by @var{style} are ignored.

The optional input and output argument @var{h} allows an axis handle to 
be passed to @code{contour} and the handles to the contour objects to be
returned.
@seealso{@ref{doc-contourc,,contourc}, @ref{doc-patch,,patch}, @ref{doc-plot,,plot}}
@end deftypefn


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

@example
@group
x = 0:0.1:10;
y = sin (x);
yp =  0.1 .* randn (size (x));
ym = -0.1 .* randn (size (x));
errorbar (x, sin (x), ym, yp);
@end group
@end example

@noindent
produces the figure shown in @ref{fig:errorbar}.

@float Figure,fig:errorbar
@center @image{errorbar,4in}
@caption{Errorbar plot.}
@end float

@c ./plot/errorbar.m
@anchor{doc-errorbar}
@deftypefn {Function File} {} errorbar (@var{args})
This function produces two-dimensional plots with errorbars.  Many
different combinations of arguments are possible.  The simplest form is

@example
errorbar (@var{y}, @var{ey})
@end example

@noindent
where the first argument is taken as the set of @var{y} coordinates
and the second argument @var{ey} is taken as the errors of the
@var{y} values.  @var{x} coordinates are taken to be the indices
of the elements, starting with 1.

If more than two arguments are given, they are interpreted as

@example
errorbar (@var{x}, @var{y}, @dots{}, @var{fmt}, @dots{})
@end example

@noindent
where after @var{x} and @var{y} there can be up to four error
parameters such as @var{ey}, @var{ex}, @var{ly}, @var{uy}, etc.,
depending on the plot type.  Any number of argument sets may appear,
as long as they are separated with a format string @var{fmt}.

If @var{y} is a matrix, @var{x} and error parameters must also be matrices
having same dimensions.  The columns of @var{y} are plotted versus the
corresponding columns of @var{x} and errorbars are drawn from
the corresponding columns of error parameters.

If @var{fmt} is missing, yerrorbars ("~") plot style is assumed.

If the @var{fmt} argument is supplied, it is interpreted as in
normal plots.  In addition the following plot styles are supported by
errorbar:

@table @samp
@item ~
Set yerrorbars plot style (default).

@item >
Set xerrorbars plot style.

@item ~>
Set xyerrorbars plot style.

@item #
Set boxes plot style.

@item #~
Set boxerrorbars plot style.

@item #~>
Set boxxyerrorbars plot style.
@end table

Examples:

@example
errorbar (@var{x}, @var{y}, @var{ex}, ">")
@end example

produces an xerrorbar plot of @var{y} versus @var{x} with @var{x}
errorbars drawn from @var{x}-@var{ex} to @var{x}+@var{ex}.

@example
@group
errorbar (@var{x}, @var{y1}, @var{ey}, "~",
          @var{x}, @var{y2}, @var{ly}, @var{uy})
@end group
@end example

produces yerrorbar plots with @var{y1} and @var{y2} versus @var{x}.
Errorbars for @var{y1} are drawn from @var{y1}-@var{ey} to
@var{y1}+@var{ey}, errorbars for @var{y2} from @var{y2}-@var{ly} to
@var{y2}+@var{uy}.

@example
@group
errorbar (@var{x}, @var{y}, @var{lx}, @var{ux},
          @var{ly}, @var{uy}, "~>")
@end group
@end example

produces an xyerrorbar plot of @var{y} versus @var{x} in which
@var{x} errorbars are drawn from @var{x}-@var{lx} to @var{x}+@var{ux}
and @var{y} errorbars from @var{y}-@var{ly} to @var{y}+@var{uy}.
@seealso{@ref{doc-semilogxerr,,semilogxerr}, @ref{doc-semilogyerr,,semilogyerr}, @ref{doc-loglogerr,,loglogerr}}
@end deftypefn


@c ./plot/semilogxerr.m
@anchor{doc-semilogxerr}
@deftypefn {Function File} {} semilogxerr (@var{args})
Produce two-dimensional plots on a semilogarithm axis with errorbars.
Many different combinations of arguments are possible.  The most used
form is

@example
semilogxerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a semi-logarithm plot of @var{y} versus @var{x}
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}.  See errorbar for available formats and 
additional information.
@seealso{@ref{doc-errorbar,,errorbar}, @ref{doc-loglogerr,,loglogerr}, @ref{doc-semilogyerr,,semilogyerr}}
@end deftypefn


@c ./plot/semilogyerr.m
@anchor{doc-semilogyerr}
@deftypefn {Function File} {} semilogyerr (@var{args})
Produce two-dimensional plots on a semilogarithm axis with errorbars.
Many different combinations of arguments are possible.  The most used
form is

@example
semilogyerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a semi-logarithm plot of @var{y} versus @var{x}
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}.  See errorbar for available formats and 
additional information.
@seealso{@ref{doc-errorbar,,errorbar}, @ref{doc-loglogerr,,loglogerr}, @ref{doc-semilogxerr,,semilogxerr}}
@end deftypefn


@c ./plot/loglogerr.m
@anchor{doc-loglogerr}
@deftypefn {Function File} {} loglogerr (@var{args})
Produce two-dimensional plots on double logarithm axis with
errorbars.  Many different combinations of arguments are possible.
The most used form is

@example
loglogerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a double logarithm plot of @var{y} versus @var{x} 
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}.  See errorbar for available formats and 
additional information.
@seealso{@ref{doc-errorbar,,errorbar}, @ref{doc-semilogxerr,,semilogxerr}, @ref{doc-semilogyerr,,semilogyerr}}
@end deftypefn


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

@example
polar (0:0.1:10*pi, 0:0.1:10*pi);
@end example

@noindent
produces the spiral plot shown in @ref{fig:polar}.

@float Figure,fig:polar
@center @image{polar,4in}
@caption{Polar plot.}
@end float

@c ./plot/polar.m
@anchor{doc-polar}
@deftypefn {Function File} {} polar (@var{theta}, @var{rho}, @var{fmt})
Make a two-dimensional plot given the polar coordinates @var{theta} and
@var{rho}.

The optional third argument specifies the line type.
@seealso{@ref{doc-plot,,plot}}
@end deftypefn


@c ./plot/pie.m
@anchor{doc-pie}
@deftypefn {Function File} {} pie (@var{y})
@deftypefnx {Function File} {} pie (@var{y}, @var{explode})
@deftypefnx {Function File} {} pie (@dots{}, @var{labels})
@deftypefnx {Function File} {} pie (@var{h}, @dots{});
@deftypefnx {Function File} {@var{h} =} pie (@dots{});
Produce a pie chart. 

Called with a single vector argument, produces a pie chart of the
elements in @var{x}, with the size of the slice determined by percentage
size of the values of @var{x}.

The variable @var{explode} is a vector of the same length as @var{x} that
if non zero 'explodes' the slice from the pie chart.

If given @var{labels} is a cell array of strings of the same length as
@var{x}, giving the labels of each of the slices of the pie chart. 

The optional return value @var{h} provides a handle to the patch object.

@seealso{@ref{doc-bar,,bar}, @ref{doc-stem,,stem}}
@end deftypefn


@c ./plot/quiver.m
@anchor{doc-quiver}
@deftypefn {Function File} {} quiver (@var{u}, @var{v})
@deftypefnx {Function File} {} quiver (@var{x}, @var{y}, @var{u}, @var{v})
@deftypefnx {Function File} {} quiver (@dots{}, @var{s})
@deftypefnx {Function File} {} quiver (@dots{}, @var{style})
@deftypefnx {Function File} {} quiver (@dots{}, 'filled')
@deftypefnx {Function File} {} quiver (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} quiver (@dots{})

Plot the @code{(@var{u}, @var{v})} components of a vector field in 
an @code{(@var{x}, @var{y})} meshgrid.  If the grid is uniform, you can 
specify @var{x} and @var{y} as vectors.

If @var{x} and @var{y} are undefined they are assumed to be
@code{(1:@var{m}, 1:@var{n})} where @code{[@var{m}, @var{n}] = 
size(@var{u})}.

The variable @var{s} is a scalar defining a scaling factor to use for
 the arrows of the field relative to the mesh spacing.  A value of 0 
disables all scaling.  The default value is 1.

The style to use for the plot can be defined with a line style @var{style}
in a similar manner to the line styles used with the @code{plot} command.
If a marker is specified then markers at the grid points of the vectors are
printed rather than arrows.  If the argument 'filled' is given then the
markers as filled.

The optional return value @var{h} provides a quiver group that
regroups the components of the quiver plot (body, arrow and marker),
and allows them to be changed together

@example
@group
[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);
@end group
@end example

@seealso{@ref{doc-plot,,plot}}
@end deftypefn


@c ./plot/quiver3.m
@anchor{doc-quiver3}
@deftypefn {Function File} {} quiver3 (@var{u}, @var{v}, @var{w})
@deftypefnx {Function File} {} quiver3 (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w})
@deftypefnx {Function File} {} quiver3 (@dots{}, @var{s})
@deftypefnx {Function File} {} quiver3 (@dots{}, @var{style})
@deftypefnx {Function File} {} quiver3 (@dots{}, 'filled')
@deftypefnx {Function File} {} quiver3 (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} quiver3 (@dots{})

Plot the @code{(@var{u}, @var{v}, @var{w})} components of a vector field in 
an @code{(@var{x}, @var{y}), @var{z}} meshgrid.  If the grid is uniform, you 
can specify @var{x}, @var{y} @var{z} as vectors.

If @var{x}, @var{y} and @var{z} are undefined they are assumed to be
@code{(1:@var{m}, 1:@var{n}, 1:@var{p})} where @code{[@var{m}, @var{n}] = 
size(@var{u})} and @code{@var{p} = max (size (@var{w}))}.

The variable @var{s} is a scalar defining a scaling factor to use for
 the arrows of the field relative to the mesh spacing.  A value of 0 
disables all scaling.  The default value is 1.

The style to use for the plot can be defined with a line style @var{style}
in a similar manner to the line styles used with the @code{plot} command.
If a marker is specified then markers at the grid points of the vectors are
printed rather than arrows.  If the argument 'filled' is given then the
markers as filled.

The optional return value @var{h} provides a quiver group that
regroups the components of the quiver plot (body, arrow and marker),
and allows them to be changed together

@example
@group
[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);
@end group
@end example

@seealso{@ref{doc-plot,,plot}}
@end deftypefn


@c ./plot/compass.m
@anchor{doc-compass}
@deftypefn {Function File} {} compass (@var{u}, @var{v})
@deftypefnx {Function File} {} compass (@var{z})
@deftypefnx {Function File} {} compass (@dots{}, @var{style})
@deftypefnx {Function File} {} compass (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} compass (@dots{})

Plot the @code{(@var{u}, @var{v})} components of a vector field emanating
from the origin of a polar plot.  If a single complex argument @var{z} is 
given, then @code{@var{u} = real (@var{z})} and @code{@var{v} = imag 
(@var{z})}.

The style to use for the plot can be defined with a line style @var{style}
in a similar manner to the line styles used with the @code{plot} command.

The optional return value @var{h} provides a list of handles to the 
the parts of the vector field (body, arrow and marker).

@example
@group
a = toeplitz([1;randn(9,1)],[1,randn(1,9)]);
compass (eig (a))
@end group
@end example

@seealso{@ref{doc-plot,,plot}, @ref{doc-polar,,polar}, @ref{doc-quiver,,quiver}, @ref{doc-feather,,feather}}
@end deftypefn


@c ./plot/feather.m
@anchor{doc-feather}
@deftypefn {Function File} {} feather (@var{u}, @var{v})
@deftypefnx {Function File} {} feather (@var{z})
@deftypefnx {Function File} {} feather (@dots{}, @var{style})
@deftypefnx {Function File} {} feather (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} feather (@dots{})

Plot the @code{(@var{u}, @var{v})} components of a vector field emanating
from equidistant points on the x-axis.  If a single complex argument
@var{z} is given, then @code{@var{u} = real (@var{z})} and
@code{@var{v} = imag (@var{z})}.

The style to use for the plot can be defined with a line style @var{style}
in a similar manner to the line styles used with the @code{plot} command.

The optional return value @var{h} provides a list of handles to the 
the parts of the vector field (body, arrow and marker).

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

@seealso{@ref{doc-plot,,plot}, @ref{doc-quiver,,quiver}, @ref{doc-compass,,compass}}
@end deftypefn


@c ./plot/pcolor.m
@anchor{doc-pcolor}
@deftypefn {Function File} {} pcolor (@var{x}, @var{y}, @var{c})
@deftypefnx {Function File} {} pcolor (@var{c})
Density plot for given matrices @var{x}, and @var{y} from @code{meshgrid} and
a matrix @var{c} corresponding to the @var{x} and @var{y} coordinates of
the mesh's vertices.  If @var{x} and @var{y} are vectors, then a typical vertex
is (@var{x}(j), @var{y}(i), @var{c}(i,j)).  Thus, columns of @var{c}
correspond to different @var{x} values and rows of @var{c} correspond
to different @var{y} values.

The @code{colormap} is scaled to the extents of @var{c}.
Limits may be placed on the color axis by the
command @code{caxis}, or by setting the @code{clim} property of the
parent axis.

The face color of each cell of the mesh is determined by interpolating
the values of @var{c} for the cell's vertices.  Contrast this with 
@code{imagesc} which renders one cell for each element of @var{c}.

@code{shading} modifies an attribute determining the manner by which the
face color of each cell is interpolated from the values of @var{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.

@var{h} is the handle to the surface object.

@seealso{@ref{doc-caxis,,caxis}, @ref{doc-contour,,contour}, @ref{doc-meshgrid,,meshgrid}, @ref{doc-imagesc,,imagesc}, @ref{doc-shading,,shading}}
@end deftypefn


@c ./plot/area.m
@anchor{doc-area}
@deftypefn {Function File} {} area (@var{x}, @var{y})
@deftypefnx {Function File} {} area (@var{x}, @var{y}, @var{lvl})
@deftypefnx {Function File} {} area (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} area (@var{y}, @dots{})
@deftypefnx {Function File} {} area (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} area (@dots{})
Area plot of cumulative sum of the columns of @var{y}.  This shows the
contributions of a value to a sum, and is functionally similar to 
@code{plot (@var{x}, cumsum (@var{y}, 2))}, except that the area under 
the curve is shaded.

If the @var{x} argument is omitted it is assumed to be given by
@code{1 : rows (@var{y})}.  A value @var{lvl} can be defined that determines
where the base level of the shading under the curve should be defined.

Additional arguments to the @code{area} function are passed to the 
@code{patch}.  The optional return value @var{h} provides a handle to 
area series object representing the patches of the areas.
@seealso{@ref{doc-plot,,plot}, @ref{doc-patch,,patch}}
@end deftypefn


@c ./plot/comet.m
@anchor{doc-comet}
@deftypefn {Function File} {} comet (@var{y})
@deftypefnx {Function File} {} comet (@var{x}, @var{y})
@deftypefnx {Function File} {} comet (@var{x}, @var{y}, @var{p})
@deftypefnx {Function File} {} comet (@var{ax}, @dots{})
Produce a simple comet style animation along the trajectory provided by 
the input coordinate vectors (@var{x}, @var{y}), where @var{x} will default
to the indices of @var{y}.

The speed of the comet may be controlled by @var{p}, which represents the
time which passes as the animation passes from one point to the next.  The
default for @var{p} is 0.1 seconds.

If @var{ax} is specified the animation is produced in that axis rather than
the @code{gca}.
@end deftypefn


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.

@c ./plot/axis.m
@anchor{doc-axis}
@deftypefn {Function File} {} axis (@var{limits})
Set axis limits for plots.

The argument @var{limits} should be a 2, 4, or 6 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, and the
fifth and sixth specify the limits for the z-axis.

Without any arguments, @code{axis} turns autoscaling on.  

With one output argument, @code{x = axis} returns the current axes 

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

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

@noindent
forces a square aspect ratio, and

@example
axis ("labely", "tic");
@end example

@noindent
turns tic marks on for all axes and tic mark labels on for the y-axis
only.

@noindent
The following options control the aspect ratio of the axes.

@table @code
@item "square"
Force a square aspect ratio.
@item "equal"
Force x distance to equal y-distance.
@item "normal"
Restore the balance.
@end table

@noindent
The following options control the way axis limits are interpreted.

@table @code
@item "auto" 
Set the specified axes to have nice limits around the data
or all if no axes are specified.
@item "manual" 
Fix the current axes limits.
@item "tight"
Fix axes to the limits of the data.
@end table

@noindent
The option @code{"image"} is equivalent to @code{"tight"} and
@code{"equal"}.

@noindent
The following options affect the appearance of tic marks.

@table @code
@item "on" 
Turn tic marks and labels on for all axes.
@item "off"
Turn tic marks off for all axes.
@item "tic[xyz]"
Turn tic marks on for all axes, or turn them on for the
specified axes and off for the remainder.
@item "label[xyz]"
Turn tic labels on for all axes, or turn them on for the 
specified axes and off for the remainder.
@item "nolabel"
Turn tic labels off for all axes.
@end table
Note, if there are no tic marks for an axis, there can be no labels.

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

@table @code
@item "ij"
Reverse y-axis, so lower values are nearer the top.
@item "xy" 
Restore y-axis, so higher values are nearer the top. 
@end table

If an axes handle is passed as the first argument, then operate on
this axes rather than the current axes.
@end deftypefn


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

@c ./plot/caxis.m
@anchor{doc-caxis}
@deftypefn {Function File} {} caxis (@var{limits})
@deftypefnx {Function File} {} caxis (@var{h}, @dots{})
Set color axis limits for plots.

The argument @var{limits} should be a 2 element vector specifying the 
lower and upper limits to assign to the first and last value in the
colormap.  Values outside this range are clamped to the first and last
colormap entries. 

If @var{limits} is 'auto', then automatic colormap scaling is applied,
whereas if @var{limits} is 'manual' the colormap scaling is set to manual.

Called without any arguments to current color axis limits are returned.

If an axes handle is passed as the first argument, then operate on
this axes rather than the current axes.
@end deftypefn


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

@anchor{doc-ylim}
@anchor{doc-zlim}
@c ./plot/xlim.m
@anchor{doc-xlim}
@deftypefn {Function File} {@var{xl} =} xlim ()
@deftypefnx {Function File} {} xlim (@var{xl})
@deftypefnx {Function File} {@var{m} =} xlim ('mode')
@deftypefnx {Function File} {} xlim (@var{m})
@deftypefnx {Function File} {} xlim (@var{h}, @dots{})
Get or set the limits of the x-axis of the current plot.  Called without
arguments @code{xlim} returns the x-axis limits of the current plot.
If passed a two element vector @var{xl}, the limits of the x-axis are set
to this value.

The current mode for calculation of the x-axis can be returned with a
call @code{xlim ('mode')}, and can be either 'auto' or 'manual'.  The 
current plotting mode can be set by passing either 'auto' or 'manual' 
as the argument.

If passed an handle as the first argument, then operate on this handle
rather than the current axes handle.
@seealso{@ref{doc-ylim,,ylim}, @ref{doc-zlim,,zlim}, @ref{doc-set,,set}, @ref{doc-get,,get}, @ref{doc-gca,,gca}}
@end deftypefn


@menu
* Two-dimensional Function Plotting::
@end menu

@node Two-dimensional Function Plotting
@subsubsection 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 @code{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,

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

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

@c ./plot/fplot.m
@anchor{doc-fplot}
@deftypefn {Function File} {} fplot (@var{fn}, @var{limits})
@deftypefnx {Function File} {} fplot (@var{fn}, @var{limits}, @var{tol})
@deftypefnx {Function File} {} fplot (@var{fn}, @var{limits}, @var{n})
@deftypefnx {Function File} {} fplot (@dots{}, @var{fmt})
Plot a function @var{fn}, within the defined limits.  @var{fn}
an be either a string, a function handle or an inline function.
The limits of the plot are given by @var{limits} of the form
@code{[@var{xlo}, @var{xhi}]} or @code{[@var{xlo}, @var{xhi},
@var{ylo}, @var{yhi}]}.  @var{tol} is the default tolerance to use for the
plot, and if @var{tol} is an integer it is assumed that it defines the 
number points to use in the plot.  The @var{fmt} argument is passed
to the plot command.

@example
@group
   fplot ("cos", [0, 2*pi])
   fplot ("[cos(x), sin(x)]", [0, 2*pi])
@end group
@end example
@seealso{@ref{doc-plot,,plot}}
@end deftypefn


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

@c ./plot/ezplot.m
@anchor{doc-ezplot}
@deftypefn {Function File} {} ezplot (@var{f})
@deftypefnx {Function File} {} ezplot (@var{fx}, @var{fy})
@deftypefnx {Function File} {} ezplot (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezplot (@dots{}, @var{n})
@deftypefnx {Function File} {} ezplot (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezplot (@dots{})

Plots in two-dimensions the curve defined by @var{f}.  The function
@var{f} may be a string, inline function or function handle and can
have either one or two variables.  If @var{f} has one variable, then 
the function is plotted over the domain @code{-2*pi < @var{x} < 2*pi}  
with 500 points. 

If @var{f} has two variables then @code{@var{f}(@var{x},@var{y}) = 0}
is calculated over the meshed domain @code{-2*pi < @var{x} | @var{y}
< 2*pi} with 60 by 60 in the mesh.  For example

@example
ezplot (@@(@var{x}, @var{y}) @var{x} .^ 2 - @var{y} .^ 2 - 1)
@end example

If two functions are passed as strings, inline functions or function
handles, then the parametric function

@example
@group
@var{x} = @var{fx} (@var{t})
@var{y} = @var{fy} (@var{t})
@end group
@end example

is plotted over the domain @code{-2*pi < @var{t} < 2*pi} with 500
points. 

If @var{dom} is a two element vector, it represents the minimum and maximum
value of @var{x}, @var{y} and @var{t}.  If it is a four element
vector, then the minimum and maximum values of @var{x} and @var{t}
are determined by the first two elements and the minimum and maximum
of @var{y} by the second pair of elements.

@var{n} is a scalar defining the number of points to use in plotting
the function.

The optional return value @var{h} provides a list of handles to the 
the line objects plotted.

@seealso{@ref{doc-plot,,plot}, @ref{doc-ezplot3,,ezplot3}}
@end deftypefn


@c ./plot/ezcontour.m
@anchor{doc-ezcontour}
@deftypefn {Function File} {} ezcontour (@var{f})
@deftypefnx {Function File} {} ezcontour (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezcontour (@dots{}, @var{n})
@deftypefnx {Function File} {} ezcontour (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezcontour (@dots{})

Plots the contour lines of a function.  @var{f} is a string, inline function
or function handle with two arguments defining the function.  By default the
plot is over the domain @code{-2*pi < @var{x} < 2*pi} and @code{-2*pi < 
@var{y} < 2*pi} with 60 points in each dimension. 

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use in each dimension.

The optional return value @var{h} provides a list of handles to the 
the parts of the vector field (body, arrow and marker).

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

@seealso{@ref{doc-ezplot,,ezplot}, @ref{doc-ezcontourf,,ezcontourf}, @ref{doc-ezsurfc,,ezsurfc}, @ref{doc-ezmeshc,,ezmeshc}}
@end deftypefn


@c ./plot/ezcontourf.m
@anchor{doc-ezcontourf}
@deftypefn {Function File} {} ezcontourf (@var{f})
@deftypefnx {Function File} {} ezcontourf (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezcontourf (@dots{}, @var{n})
@deftypefnx {Function File} {} ezcontourf (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezcontourf (@dots{})

Plots the filled contour lines of a function.  @var{f} is a string, inline 
function or function handle with two arguments defining the function.  By 
default the plot is over the domain @code{-2*pi < @var{x} < 2*pi} and 
@code{-2*pi < @var{y} < 2*pi} with 60 points in each dimension. 

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use in each dimension.

The optional return value @var{h} provides a list of handles to the 
the parts of the vector field (body, arrow and marker).

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

@seealso{@ref{doc-ezplot,,ezplot}, @ref{doc-ezcontour,,ezcontour}, @ref{doc-ezsurfc,,ezsurfc}, @ref{doc-ezmeshc,,ezmeshc}}
@end deftypefn


@c ./plot/ezpolar.m
@anchor{doc-ezpolar}
@deftypefn {Function File} {} ezpolar (@var{f})
@deftypefnx {Function File} {} ezpolar (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezpolar (@dots{}, @var{n})
@deftypefnx {Function File} {} ezpolar (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezpolar (@dots{})

Plots in polar plot defined by a function.  The function @var{f} is either
a string, inline function or function handle with one arguments defining 
the function.  By default the plot is over the domain @code{0 < @var{x} < 
2*pi} with 60 points. 

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{t}.  @var{n} is a scalar defining the number of points to 
use.

The optional return value @var{h} provides a list of handles to the 
the parts of the vector field (body, arrow and marker).

@example
ezpolar (@@(t) 1 + sin (t));
@end example

@seealso{@ref{doc-polar,,polar}, @ref{doc-ezplot,,ezplot}, @ref{doc-ezsurf,,ezsurf}, @ref{doc-ezmesh,,ezmesh}}
@end deftypefn


@node Three-Dimensional Plotting
@subsection Three-Dimensional Plotting

The function @code{mesh} produces mesh surface plots.  For example,

@example
@group
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);
@end group
@end example

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

@float Figure,fig:mesh
@center @image{mesh,4in}
@caption{Mesh plot.}
@end float

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

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

@example
@group
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);
@end group
@end example

@noindent
displays the spiral in three dimensions shown in @ref{fig:plot3}.

@float Figure,fig:plot3
@center @image{plot3,4in}
@caption{Three dimensional spiral.}
@end float

Finally, the @code{view} function changes the viewpoint for
three-dimensional plots.

@c ./plot/mesh.m
@anchor{doc-mesh}
@deftypefn {Function File} {} mesh (@var{x}, @var{y}, @var{z})
Plot a mesh given matrices @var{x}, and @var{y} from @code{meshgrid} and
a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of
the mesh.  If @var{x} and @var{y} are vectors, then a typical vertex
is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns of @var{z}
correspond to different @var{x} values and rows of @var{z} correspond
to different @var{y} values.
@seealso{@ref{doc-meshgrid,,meshgrid}, @ref{doc-contour,,contour}}
@end deftypefn


@c ./plot/meshc.m
@anchor{doc-meshc}
@deftypefn {Function File} {} meshc (@var{x}, @var{y}, @var{z})
Plot a mesh and contour given matrices @var{x}, and @var{y} from 
@code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and 
@var{y} coordinates of the mesh.  If @var{x} and @var{y} are vectors, 
then a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, 
columns of @var{z} correspond to different @var{x} values and rows of 
@var{z} correspond to different @var{y} values.
@seealso{@ref{doc-meshgrid,,meshgrid}, @ref{doc-mesh,,mesh}, @ref{doc-contour,,contour}}
@end deftypefn


@c ./plot/meshz.m
@anchor{doc-meshz}
@deftypefn {Function File} {} meshz (@var{x}, @var{y}, @var{z})
Plot a curtain mesh given matrices @var{x}, and @var{y} from 
@code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and 
@var{y} coordinates of the mesh.  If @var{x} and @var{y} are vectors, 
then a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, 
columns of @var{z} correspond to different @var{x} values and rows of 
@var{z} correspond to different @var{y} values.
@seealso{@ref{doc-meshgrid,,meshgrid}, @ref{doc-mesh,,mesh}, @ref{doc-contour,,contour}}
@end deftypefn


@c ./plot/hidden.m
@anchor{doc-hidden}
@deftypefn {Function File} {} hidden (@var{mode})
@deftypefnx {Function File} {} hidden ()
Manipulation the mesh hidden line removal.  Called with no argument
the hidden line removal is toggled.  The argument @var{mode} can be either
'on' or 'off' and the set of the hidden line removal is set accordingly.
@seealso{@ref{doc-mesh,,mesh}, @ref{doc-meshc,,meshc}, @ref{doc-surf,,surf}}
@end deftypefn


@c ./plot/surf.m
@anchor{doc-surf}
@deftypefn {Function File} {} surf (@var{x}, @var{y}, @var{z})
Plot a surface given matrices @var{x}, and @var{y} from @code{meshgrid} and
a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of
the mesh.  If @var{x} and @var{y} are vectors, then a typical vertex
is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns of @var{z}
correspond to different @var{x} values and rows of @var{z} correspond
to different @var{y} values.
@seealso{@ref{doc-mesh,,mesh}, @ref{doc-surface,,surface}}
@end deftypefn


@c ./plot/surfc.m
@anchor{doc-surfc}
@deftypefn {Function File} {} surfc (@var{x}, @var{y}, @var{z})
Plot a surface and contour given matrices @var{x}, and @var{y} from 
@code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and 
@var{y} coordinates of the mesh.  If @var{x} and @var{y} are vectors, 
then a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, 
columns of @var{z} correspond to different @var{x} values and rows of 
@var{z} correspond to different @var{y} values.
@seealso{@ref{doc-meshgrid,,meshgrid}, @ref{doc-surf,,surf}, @ref{doc-contour,,contour}}
@end deftypefn


@c ./plot/surfl.m
@anchor{doc-surfl}
@deftypefn {Function File} {} surfl (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surfl (@var{z})
@deftypefnx {Function File} {} surfl (@var{x}, @var{y}, @var{z}, @var{L})
@deftypefnx {Function File} {} surfl (@var{x}, @var{y}, @var{z}, @var{L}, @var{P})
@deftypefnx {Function File} {} surfl (@dots{},"light")
Plot a lighted surface given matrices @var{x}, and @var{y} from @code{meshgrid} and
a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of
the mesh.  If @var{x} and @var{y} are vectors, then a typical vertex
is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns of @var{z}
correspond to different @var{x} values and rows of @var{z} correspond
to different @var{y} values.

The light direction can be specified using @var{L}.  It can be
given as 2-element vector [azimuth, elevation] in degrees or as 3-element vector [lx, ly, lz].
The default value is rotated 45° counter-clockwise from the current view.

The material properties of the surface can specified using a 4-element vector
@var{P} = [@var{AM} @var{D} @var{SP} @var{exp}] which defaults to
@var{p} = [0.55 0.6 0.4 10]. 
@table @code
@item "AM" strength of ambient light
@item "D" strength of diffuse reflection
@item "SP" strength of specular reflection
@item "EXP" specular exponent
@end table

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

Example:

@example
@group
colormap(bone);
surfl(peaks);
shading interp;
@end group
@end example
@seealso{@ref{doc-surf,,surf}, @ref{doc-diffuse,,diffuse}, @ref{doc-specular,,specular}, @ref{doc-surface,,surface}}
@end deftypefn


@c ./plot/surfnorm.m
@anchor{doc-surfnorm}
@deftypefn {Function File} {} surfnorm (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surfnorm (@var{z})
@deftypefnx {Function File} {[@var{nx}, @var{ny}, @var{nz}] =} surfnorm (@dots{})
@deftypefnx {Function File} {} surfnorm (@var{h}, @dots{})
Find the vectors normal to a meshgridded surface.  The meshed gridded 
surface is defined by @var{x}, @var{y}, and @var{z}.  If @var{x} and 
@var{y} are not defined, then it is assumed that they are given by

@example
@group
[@var{x}, @var{y}] = meshgrid (1:size(@var{z}, 1), 
                     1:size(@var{z}, 2));
@end group
@end example

If no return arguments are requested, a surface plot with the normal 
vectors to the surface is plotted.  Otherwise the components of the normal
vectors at the mesh gridded points are returned in @var{nx}, @var{ny},
and @var{nz}.

The normal vectors are calculated by taking the cross product of the 
diagonals of each of the quadrilaterals in the meshgrid to find the 
normal vectors of the centers of these quadrilaterals.  The four nearest
normal vectors to the meshgrid points are then averaged to obtain the 
normal to the surface at the meshgridded points.

An example of the use of @code{surfnorm} is

@example
surfnorm (peaks (25));
@end example
@seealso{@ref{doc-surf,,surf}, @ref{doc-quiver3,,quiver3}}
@end deftypefn


@c ./plot/diffuse.m
@anchor{doc-diffuse}
@deftypefn {Function File} {} diffuse (@var{sx}, @var{sy}, @var{sz}, @var{l})
Calculate diffuse reflection strength of a surface defined by the normal
vector elements @var{sx}, @var{sy}, @var{sz}. 
The light vector can be specified using parameter @var{L}.  It can be
given as 2-element vector [azimuth, elevation] in degrees or as 3-element
vector [lx, ly, lz]. 
@seealso{@ref{doc-specular,,specular}, @ref{doc-surfl,,surfl}}
@end deftypefn


@c ./plot/specular.m
@anchor{doc-specular}
@deftypefn {Function File} {} specular (@var{sx}, @var{sy}, @var{sz}, @var{l}, @var{v})
@deftypefnx {Function File} {} specular (@var{sx}, @var{sy}, @var{sz}, @var{l}, @var{v}, @var{se})
Calculate specular reflection strength of a surface defined by the normal
vector elements @var{sx}, @var{sy}, @var{sz} using Phong's approximation. 
The light and view vectors can be specified using parameter @var{L} and @var{V} respectively.
Both can be given as 2-element vectors [azimuth, elevation] in degrees or as 3-element
vector [x, y, z].  An optional 6th argument describes the specular exponent (spread) @var{se}.
@seealso{@ref{doc-surfl,,surfl}, @ref{doc-diffuse,,diffuse}}
@end deftypefn


@c ./plot/meshgrid.m
@anchor{doc-meshgrid}
@deftypefn {Function File} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@var{x}, @var{y})
@deftypefnx {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@var{x})
Given vectors of @var{x} and @var{y} and @var{z} coordinates, and
returning 3 arguments, return three-dimensional arrays corresponding
to the @var{x}, @var{y}, and @var{z} coordinates of a mesh.  When
returning only 2 arguments, return matrices corresponding to the
@var{x} and @var{y} coordinates of a mesh.  The rows of @var{xx} are
copies of @var{x}, and the columns of @var{yy} are copies of @var{y}.
If @var{y} is omitted, then it is assumed to be the same as @var{x},
and @var{z} is assumed the same as @var{y}.
@seealso{@ref{doc-mesh,,mesh}, @ref{doc-contour,,contour}}
@end deftypefn


@c ./plot/ndgrid.m
@anchor{doc-ndgrid}
@deftypefn {Function File} {[@var{y1}, @var{y2}, @dots{},  @var{y}n] =} ndgrid (@var{x1}, @var{x2}, @dots{}, @var{x}n)
@deftypefnx {Function File} {[@var{y1}, @var{y2}, @dots{},  @var{y}n] =} ndgrid (@var{x})
Given n vectors @var{x1}, @dots{} @var{x}n, @code{ndgrid} returns
n arrays of dimension n. The elements of the i-th output argument
contains the elements of the vector @var{x}i repeated over all
dimensions different from the i-th dimension.  Calling ndgrid with
only one input argument @var{x} is equivalent of calling ndgrid with
all n input arguments equal to @var{x}:

[@var{y1}, @var{y2}, @dots{},  @var{y}n] = ndgrid (@var{x}, @dots{}, @var{x})
@seealso{@ref{doc-meshgrid,,meshgrid}}
@end deftypefn


@c ./plot/plot3.m
@anchor{doc-plot3}
@deftypefn {Function File} {} plot3 (@var{args})
Produce three-dimensional plots.  Many different combinations of
arguments are possible.  The simplest form is

@example
plot3 (@var{x}, @var{y}, @var{z})
@end example

@noindent
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 the matrices 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

@example
plot3 (@var{x}, @var{c})
@end example

@noindent
the real and imaginary parts of the second argument are used
as the @var{y} and @var{z} coordinates, respectively.

If only one argument is given, as

@example
plot3 (@var{c})
@end example

@noindent
the real and imaginary parts of the argument are used as the @var{y}
and @var{z} values, and they are plotted versus their index.

Arguments may also be given in groups of three as

@example
plot3 (@var{x1}, @var{y1}, @var{z1}, @var{x2}, @var{y2}, @var{z2}, @dots{})
@end example

@noindent
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

@example
plot3 (@var{x1}, @var{c1}, "", @var{c2}, "", @dots{})
@end example

An example of the use of @code{plot3} is

@example
@group
   z = [0:0.05:5];
   plot3 (cos(2*pi*z), sin(2*pi*z), z, ";helix;");
   plot3 (z, exp(2i*pi*z), ";complex sinusoid;");
@end group
@end example
@seealso{@ref{doc-plot,,plot}, @ref{doc-xlabel,,xlabel}, @ref{doc-ylabel,,ylabel}, @ref{doc-zlabel,,zlabel}, @ref{doc-title,,title}, @ref{doc-print,,print}}
@end deftypefn


@c ./plot/view.m
@anchor{doc-view}
@deftypefn {Function File} {} view (@var{azimuth}, @var{elevation})
@deftypefnx {Function File} {} view (@var{dims})
@deftypefnx {Function File} {[@var{azimuth}, @var{elevation}] =} view ()
Set or get the viewpoint for the current axes.
@end deftypefn


@c ./plot/slice.m
@anchor{doc-slice}
@deftypefn {Function File} {} slice (@var{x}, @var{y}, @var{z}, @var{v}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {Function File} {} slice (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {Function File} {} slice (@var{v}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {Function File} {} slice (@var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {Function File} {@var{h} =} slice (@dots{})
@deftypefnx {Function File} {@var{h} =} slice (@dots{}, @var{method})
Plot slices of 3D data/scalar fields.  Each element of the 3-dimensional 
array @var{v} represents a scalar value at a location given by the
parameters @var{x}, @var{y}, and @var{z}.  The parameters @var{x},
@var{x}, and @var{z} are either 3-dimensional arrays of the same size
as the array @var{v} in the "meshgrid" format or vectors.  The
parameters @var{xi}, etc. respect a similar format to @var{x}, etc.,
and they represent the points at which the array @var{vi} is
interpolated using interp3.  The vectors @var{sx}, @var{sy}, and
@var{sz} contain points of orthogonal slices of the respective axes.

If @var{x}, @var{y}, @var{z} are omitted, they are assumed to be 
@code{x = 1:size (@var{v}, 2)}, @code{y = 1:size (@var{v}, 1)} and
@code{z = 1:size (@var{v}, 3)}. 

@var{Method} is one of:

@table @code
@item "nearest"
Return the nearest neighbor.
@item "linear"
Linear interpolation from nearest neighbors.
@item "cubic"
Cubic interpolation from four nearest neighbors (not implemented yet).
@item "spline"
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

The default method is @code{"linear"}.
The optional return value @var{h} is a vector of handles to the
surface graphic objects.

Examples:
@example
@group
[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);
@end group
@end example
@seealso{@ref{doc-interp3,,interp3}, @ref{doc-surface,,surface}, @ref{doc-pcolor,,pcolor}}
@end deftypefn


@c ./plot/ribbon.m
@anchor{doc-ribbon}
@deftypefn  {Function File} {} ribbon (@var{x}, @var{y}, @var{width})
@deftypefnx {Function File} {} ribbon (@var{y})
@deftypefnx {Function File} {@var{h} =} ribbon (@dots{})
Plot a ribbon plot for the columns of @var{y} vs.  @var{x}.  The
optional parameter @var{width} specifies the width of a single ribbon
(default is 0.75).  If @var{x} is omitted, a vector containing the
row numbers is assumed (1:rows(Y)).  If requested, return a vector
@var{h} of the handles to the surface objects.
@seealso{@ref{doc-gca,,gca}, @ref{doc-colorbar,,colorbar}}
@end deftypefn


@c ./plot/shading.m
@anchor{doc-shading}
@deftypefn {Function File} {} shading (@var{type})
@deftypefnx {Function File} {} shading (@var{ax}, @dots{})
Set the shading of surface or patch graphic objects.  Valid arguments
for @var{type} are

@table @code
@item "flat"
Single colored patches with invisible edges.

@item "faceted"
Single colored patches with visible edges.

@item "interp"
Color between patch vertices are interpolated and the patch edges are
invisible.
@end table

If @var{ax} is given the shading is applied to axis @var{ax} instead
of the current axis.
@end deftypefn


@menu
* Three-dimensional Function Plotting::
* Three-dimensional Geometric Shapes::
@end menu

@node Three-dimensional Function Plotting
@subsubsection Three-dimensional Function Plotting

@c ./plot/ezplot3.m
@anchor{doc-ezplot3}
@deftypefn {Function File} {} ezplot3 (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {} ezplot3 (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezplot3 (@dots{}, @var{n})
@deftypefnx {Function File} {} ezplot3 (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezplot3 (@dots{})

Plots in three-dimensions the curve defined parametrically. 
@var{fx}, @var{fy}, and @var{fz} are strings, inline functions
or function handles with one arguments defining the function.  By 
default the plot is over the domain @code{-2*pi < @var{x} < 2*pi}  
with 60 points. 

If @var{dom} is a two element vector, it represents the minimum and maximum
value of @var{t}.  @var{n} is a scalar defining the number of points to use.

The optional return value @var{h} provides a list of handles to the 
the parts of the vector field (body, arrow and marker).

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

@seealso{@ref{doc-plot3,,plot3}, @ref{doc-ezplot,,ezplot}, @ref{doc-ezsurf,,ezsurf}, @ref{doc-ezmesh,,ezmesh}}
@end deftypefn


@c ./plot/ezmesh.m
@anchor{doc-ezmesh}
@deftypefn {Function File} {} ezmesh (@var{f})
@deftypefnx {Function File} {} ezmesh (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {} ezmesh (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezmesh (@dots{}, @var{n})
@deftypefnx {Function File} {} ezmesh (@dots{}, 'circ')
@deftypefnx {Function File} {} ezmesh (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezmesh (@dots{})

Plots the mesh defined by a function.  @var{f} is a string, inline
function or function handle with two arguments defining the function.  By 
default the plot is over the domain @code{-2*pi < @var{x} < 2*pi} and
@code{-2*pi < @var{y} < 2*pi} with 60 points in each dimension. 

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use in each dimension.

If three functions are passed, then plot the parametrically defined 
function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}), 
@var{fz} (@var{s}, @var{t})]}. 

If the argument 'circ' is given, then the function is plotted over a disk
centered on the middle of the domain @var{dom}.

The optional return value @var{h} provides a list of handles to the 
the parts of the vector field (body, arrow and marker).

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

An example of a parametrically defined function is

@example
@group
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);
@end group
@end example

@seealso{@ref{doc-ezplot,,ezplot}, @ref{doc-ezsurf,,ezsurf}, @ref{doc-ezsurfc,,ezsurfc}, @ref{doc-ezmeshc,,ezmeshc}}
@end deftypefn


@c ./plot/ezmeshc.m
@anchor{doc-ezmeshc}
@deftypefn {Function File} {} ezmeshc (@var{f})
@deftypefnx {Function File} {} ezmeshc (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {} ezmeshc (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezmeshc (@dots{}, @var{n})
@deftypefnx {Function File} {} ezmeshc (@dots{}, 'circ')
@deftypefnx {Function File} {} ezmeshc (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezmeshc (@dots{})

Plots the mesh and contour lines defined by a function.  @var{f} is a string,
inline function or function handle with two arguments defining the function.
By default the plot is over the domain @code{-2*pi < @var{x} < 2*pi} and
@code{-2*pi < @var{y} < 2*pi} with 60 points in each dimension. 

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use in each dimension.

If three functions are passed, then plot the parametrically defined 
function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}), 
@var{fz} (@var{s}, @var{t})]}. 

If the argument 'circ' is given, then the function is plotted over a disk
centered on the middle of the domain @var{dom}.

The optional return value @var{h} provides a list of handles to the 
the parts of the vector field (body, arrow and marker).

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

@seealso{@ref{doc-ezplot,,ezplot}, @ref{doc-ezsurfc,,ezsurfc}, @ref{doc-ezsurf,,ezsurf}, @ref{doc-ezmesh,,ezmesh}}
@end deftypefn


@c ./plot/ezsurf.m
@anchor{doc-ezsurf}
@deftypefn {Function File} {} ezsurf (@var{f})
@deftypefnx {Function File} {} ezsurf (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {} ezsurf (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezsurf (@dots{}, @var{n})
@deftypefnx {Function File} {} ezsurf (@dots{}, 'circ')
@deftypefnx {Function File} {} ezsurf (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezsurf (@dots{})

Plots the surface defined by a function.  @var{f} is a string, inline
function or function handle with two arguments defining the function.  By 
default the plot is over the domain @code{-2*pi < @var{x} < 2*pi} and
@code{-2*pi < @var{y} < 2*pi} with 60 points in each dimension. 

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use in each dimension.

If three functions are passed, then plot the parametrically defined 
function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}), 
@var{fz} (@var{s}, @var{t})]}. 

If the argument 'circ' is given, then the function is plotted over a disk
centered on the middle of the domain @var{dom}.

The optional return value @var{h} provides a list of handles to the 
the parts of the vector field (body, arrow and marker).

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

An example of a parametrically defined function is

@example
@group
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);
@end group
@end example

@seealso{@ref{doc-ezplot,,ezplot}, @ref{doc-ezmesh,,ezmesh}, @ref{doc-ezsurfc,,ezsurfc}, @ref{doc-ezmeshc,,ezmeshc}}
@end deftypefn


@c ./plot/ezsurfc.m
@anchor{doc-ezsurfc}
@deftypefn {Function File} {} ezsurfc (@var{f})
@deftypefnx {Function File} {} ezsurfc (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {} ezsurfc (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezsurfc (@dots{}, @var{n})
@deftypefnx {Function File} {} ezsurfc (@dots{}, 'circ')
@deftypefnx {Function File} {} ezsurfc (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezsurfc (@dots{})

Plots the surface and contour lines defined by a function.  @var{f} is a
string, inline function or function handle with two arguments defining the
function.  By default the plot is over the domain @code{-2*pi < @var{x} <
2*pi} and @code{-2*pi < @var{y} < 2*pi} with 60 points in each dimension. 

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use in each dimension.

If three functions are passed, then plot the parametrically defined 
function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}), 
@var{fz} (@var{s}, @var{t})]}. 

If the argument 'circ' is given, then the function is plotted over a disk
centered on the middle of the domain @var{dom}.

The optional return value @var{h} provides a list of handles to the 
the parts of the vector field (body, arrow and marker).

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

@seealso{@ref{doc-ezplot,,ezplot}, @ref{doc-ezmeshc,,ezmeshc}, @ref{doc-ezsurf,,ezsurf}, @ref{doc-ezmesh,,ezmesh}}
@end deftypefn


@node Three-dimensional Geometric Shapes
@subsubsection Three-dimensional Geometric Shapes

@c ./plot/cylinder.m
@anchor{doc-cylinder}
@deftypefn {Function File} {} cylinder
@deftypefnx {Function File} {} cylinder (@var{r})
@deftypefnx {Function File} {} cylinder (@var{r}, @var{n})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} cylinder (@dots{})
@deftypefnx {Function File} {} cylinder (@var{ax}, @dots{})
Generates three matrices in @code{meshgrid} format, such that
@code{surf (@var{x}, @var{y}, @var{z})} generates a unit cylinder.
The matrices are of size @code{@var{n}+1}-by-@code{@var{n}+1}. 
@var{r} is a vector containing the radius along the z-axis.
If @var{n} or @var{r} are omitted then default values of 20 or [1 1]
are assumed.

Called with no return arguments, @code{cylinder} calls directly
@code{surf (@var{x}, @var{y}, @var{z})}.  If an axes handle @var{ax}
is passed as the first argument, the surface is plotted to this set
of axes.

Examples:
@example
@group
disp ("plotting a cone")
[x, y, z] = cylinder (10:-1:0,50);
surf (x, y, z);
@end group
@end example
@seealso{@ref{doc-sphere,,sphere}}
@end deftypefn


@c ./plot/sphere.m
@anchor{doc-sphere}
@deftypefn {Function File} {[@var{x}, @var{y}, @var{z}] =} sphere (@var{n})
@deftypefnx {Function File} {} sphere (@var{h}, @dots{})
Generates three matrices in @code{meshgrid} format, such that 
@code{surf (@var{x}, @var{y}, @var{z})} generates a unit sphere. 
The matrices of @code{@var{n}+1}-by-@code{@var{n}+1}.  If @var{n} is 
omitted then a default value of 20 is assumed.

Called with no return arguments, @code{sphere} call directly 
@code{surf (@var{x}, @var{y}, @var{z})}.  If an axes handle is passed
as the first argument, the surface is plotted to this set of axes.
@seealso{@ref{doc-peaks,,peaks}}
@end deftypefn


@c ./plot/ellipsoid.m
@anchor{doc-ellipsoid}
@deftypefn {Function File} {[@var{x}, @var{y}, @var{z}] =} ellipsoid (@var{xc},@var{yc}, @var{zc}, @var{xr}, @var{yr}, @var{zr}, @var{n})
@deftypefnx {Function File} {} ellipsoid (@var{h}, @dots{})
Generate three matrices in @code{meshgrid} format that define an
ellipsoid.  Called with no return arguments, @code{ellipsoid} calls
directly @code{surf (@var{x}, @var{y}, @var{z})}.  If an axes handle
is passed as the first argument, the surface is plotted to this
set of axes.
@seealso{@ref{doc-sphere,,sphere}}
@end deftypefn


@node Plot Annotations
@subsection Plot Annotations

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

@example
@group
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)");
@end group
@end example

The functions @code{grid} and @code{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.

@c ./plot/title.m
@anchor{doc-title}
@deftypefn {Function File} {} title (@var{title})
@deftypefnx {Function File} {} title (@var{title}, @var{p1}, @var{v1}, @dots{})
Create a title object and return a handle to it.
@end deftypefn


@c ./plot/legend.m
@anchor{doc-legend}
@deftypefn {Function File} {} legend (@var{st1}, @var{st2}, @dots{})
@deftypefnx {Function File} {} legend (@var{st1}, @var{st2}, @dots{}, "location", @var{pos})
@deftypefnx {Function File} {} legend (@var{matstr})
@deftypefnx {Function File} {} legend (@var{matstr}, "location", @var{pos})
@deftypefnx {Function File} {} legend (@var{cell})
@deftypefnx {Function File} {} legend (@var{cell}, "location", @var{pos})
@deftypefnx {Function File} {} legend ('@var{func}')

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.  Legend works on line graphs, bar graphs, etc.  A plot must
exist before legend is called.

The optional parameter @var{pos} specifies the location of the legend
as follows:

@multitable @columnfractions 0.06 0.14 0.80
@item @tab north @tab
  center top
@item @tab south @tab
  center bottom
@item @tab east @tab
  right center
@item @tab west @tab
  left center
@item @tab northeast @tab
  right top (default)
@item @tab northwest @tab
  left top
@item @tab southeast @tab
  right bottom
@item @tab southwest @tab
  left bottom
@item 
@item @tab outside @tab
  can be appended to any location string
@end multitable

Some specific functions are directly available using @var{func}:

@table @asis
@item "show"
  Show legends from the plot
@item "hide"
@itemx "off"
  Hide legends from the plot
@item "boxon"
  Draw a box around legends
@item "boxoff"
  Withdraw the box around legends
@item "left"
  Text is to the left of the keys
@item "right"
  Text is to the right of the keys
@end table
@end deftypefn


@c ./plot/text.m
@anchor{doc-text}
@deftypefn {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{label})
@deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{z}, @var{label})
@deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{label}, @var{p1}, @var{v1}, @dots{})
@deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{z}, @var{label}, @var{p1}, @var{v1}, @dots{})
Create a text object with text @var{label} at position @var{x},
@var{y}, @var{z} on the current axes.  Property-value pairs following
@var{label} may be used to specify the appearance of the text.
@end deftypefn


See @ref{Text Properties} for the properties that you can set.

@anchor{doc-ylabel}
@anchor{doc-zlabel}
@c ./plot/xlabel.m
@anchor{doc-xlabel}
@deftypefn {Function File} {} xlabel (@var{string})
@deftypefnx {Function File} {} ylabel (@var{string})
@deftypefnx {Function File} {} zlabel (@var{string})
@deftypefnx {Function File} {} xlabel (@var{h}, @var{string})
Specify x, y, and z axis labels for the current figure.  If @var{h} is
specified then label the axis defined by @var{h}.
@seealso{@ref{doc-plot,,plot}, @ref{doc-semilogx,,semilogx}, @ref{doc-semilogy,,semilogy}, @ref{doc-loglog,,loglog}, @ref{doc-polar,,polar}, @ref{doc-mesh,,mesh}, @ref{doc-contour,,contour}, @ref{doc-bar,,bar}, @ref{doc-stairs,,stairs}, @ref{doc-title,,title}}
@end deftypefn


@c ./plot/clabel.m
@anchor{doc-clabel}
@deftypefn {Function File} {} clabel (@var{c}, @var{h})
@deftypefnx {Function File} {} clabel (@var{c}, @var{h}, @var{v})
@deftypefnx {Function File} {} clabel (@var{c}, @var{h}, "manual")
@deftypefnx {Function File} {} clabel (@var{c})
@deftypefnx {Function File} {} clabel (@var{c}, @var{h})
@deftypefnx {Function File} {} clabel (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} clabel (@dots{})
Adds labels to the contours of a contour plot.  The contour plot is specified
by the contour matrix @var{c} and optionally the contourgroup object @var{h}
that are returned by @code{contour}, @code{contourf} and @code{contour3}.
The contour labels are rotated and placed in the contour itself.

By default, all contours are labelled.  However, the contours to label can be
specified by the vector @var{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.  Additionally,
the property "LabelSpacing" is available allowing the spacing between labels
on a contour (in points) to be specified.  The default is 144 points, or 2
inches.

The returned value @var{h} is the set of text object that represent the
contour labels.  The "userdata" property of the text objects contains the
numerical value of the contour label.

An example of the use of @code{clabel} is

@example
@group
[c, h] = contour (peaks(), -4 : 6);
clabel (c, h, -4 : 2 : 6, 'fontsize', 12);
@end group
@end example

@seealso{@ref{doc-contour,,contour}, @ref{doc-contourf,,contourf}, @ref{doc-contour3,,contour3}, @ref{doc-meshc,,meshc}, @ref{doc-surfc,,surfc}, @ref{doc-text,,text}}
@end deftypefn


@c ./plot/box.m
@anchor{doc-box}
@deftypefn {Function File} {} box (@var{arg})
@deftypefnx {Function File} {} box (@var{h}, @dots{})
Control the display of a border around the plot.
The argument may be either @code{"on"} or @code{"off"}.  If it is
omitted, the current box state is toggled.
@seealso{@ref{doc-grid,,grid}}
@end deftypefn


@c ./plot/grid.m
@anchor{doc-grid}
@deftypefn {Function File} {} grid (@var{arg})
@deftypefnx {Function File} {} grid ("minor", @var{arg2})
@deftypefnx {Function File} {} grid (@var{hax}, @dots{})
Force the display of a grid on the plot.
The argument may be either @code{"on"}, or @code{"off"}.
If it is omitted, the current grid state is toggled.

If @var{arg} is @code{"minor"} then the minor grid is toggled.  When
using a minor grid a second argument @var{arg2} is allowed, which can
be either @code{"on"} or @code{"off"} to explicitly set the state of
the minor grid.

If the first argument is an axis handle, @var{hax}, operate on the
specified axis object.
@seealso{@ref{doc-plot,,plot}}
@end deftypefn


@c ./plot/colorbar.m
@anchor{doc-colorbar}
@deftypefn {Function File} {} colorbar (@var{s})
@deftypefnx {Function File} {} colorbar ("peer", @var{h}, @dots{})
Adds a colorbar to the current axes.  Valid values for @var{s} are

@table @asis
@item "EastOutside"
Place the colorbar outside the plot to the right.  This is the default.
@item "East"
Place the colorbar inside the plot to the right.
@item "WestOutside"
Place the colorbar outside the plot to the left.
@item "West"
Place the colorbar inside the plot to the left.
@item "NorthOutside"
Place the colorbar above the plot.
@item "North"
Place the colorbar at the top of the plot.
@item "SouthOutside"
Place the colorbar under the plot.
@item "South"
Place the colorbar at the bottom of the plot.
@item "Off", "None"
Remove any existing colorbar from the plot.
@end table

If the argument "peer" is given, then the following argument is treated
as the axes handle on which to add the colorbar.
@end deftypefn


@node Multiple Plots on One Page
@subsection 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 @code{subplot} function to divide the plot
area into a series of subplot windows that are indexed by an integer.
For example,

@example
@group
subplot (2, 1, 1)
fplot (@@sin, [-10, 10]);
subplot (2, 1, 2)
fplot (@@cos, [-10, 10]);
@end group
@end example

@noindent
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 @code{subplot} is
numbered in column-major order (top to bottom, left to right).

@c ./plot/subplot.m
@anchor{doc-subplot}
@deftypefn {Function File} {} subplot (@var{rows}, @var{cols}, @var{index})
@deftypefnx {Function File} {} subplot (@var{rcn})
Set up a plot grid with @var{cols} by @var{rows} subwindows and plot
in location given by @var{index}.

If only one argument is supplied, then it must be a three digit value
specifying the location in digits 1 (rows) and 2 (columns) and the plot
index in digit 3.

The plot index runs row-wise.  First all the columns in a row are filled
and then the next row is filled.

For example, a plot with 2 by 3 grid will have plot indices running as
follows:
@tex
\vskip 10pt
\hfil\vbox{\offinterlineskip\hrule
\halign{\vrule#&&\qquad\hfil#\hfil\qquad\vrule\cr
height13pt&1&2&3\cr height12pt&&&\cr\noalign{\hrule}
height13pt&4&5&6\cr height12pt&&&\cr\noalign{\hrule}}}
\hfil
\vskip 10pt
@end tex
@ifnottex
@display
@example
@group

+-----+-----+-----+
|  1  |  2  |  3  |
+-----+-----+-----+
|  4  |  5  |  6  |
+-----+-----+-----+
@end group
@end example
@end display
@end ifnottex
@seealso{@ref{doc-plot,,plot}}
@end deftypefn


@node Multiple Plot Windows
@subsection Multiple Plot Windows

You can open multiple plot windows using the @code{figure} function.
For example

@example
@group
figure (1);
fplot (@@sin, [-10, 10]);
figure (2);
fplot (@@cos, [-10, 10]);
@end group
@end example

@noindent
creates two figures, with the first displaying a sine wave and
the second a cosine wave.  Figure numbers must be positive integers.

@c ./plot/figure.m
@anchor{doc-figure}
@deftypefn {Function File} {} figure (@var{n})
@deftypefnx {Function File} {} figure (@var{n}, @var{property}, @var{value}, @dots{})
Set the current plot window to plot window @var{n}.  If no arguments are
specified, the next available window number is chosen.

Multiple property-value pairs may be specified for the figure, but they
must appear in pairs.
@end deftypefn


@node Printing Plots
@subsection Printing Plots

The @code{print} command allows you to save plots in a variety of
formats.  For example,

@example
print -deps foo.eps
@end example

@noindent
writes the current figure to an encapsulated PostScript file called
@file{foo.eps}.

@c ./plot/print.m
@anchor{doc-print}
@deftypefn {Function File} {} print ()
@deftypefnx {Function File} {} print (@var{options})
@deftypefnx {Function File} {} print (@var{filename}, @var{options})
@deftypefnx {Function File} {} print (@var{h}, @var{filename}, @var{options})
Print a graph, or save it to a file

@var{filename} defines the file name of the output file.  If no
filename is specified, the output is sent to the printer.

@var{h} specifies the figure handle.  If no handle is specified
the handle for the current figure is used.

@var{options}:
@table @code
@item -P@var{printer}
  Set the @var{printer} name to which the graph is sent if no
@var{filename} is specified.
@item -G@var{ghostscript_command}
  Specify the command for calling Ghostscript.  For Unix and Windows,
the defaults are 'gs' and 'gswin32c', respectively.
@item -color
@itemx -mono
  Monochrome or color lines.
@item -solid
@itemx -dashed
  Solid or dashed lines.
@item -portrait
@itemx -landscape
  Specify the orientation of the plot for printed output.
@item -d@var{device}
  Output device, where @var{device} is one of:
@table @code
@item ps
@itemx ps2
@itemx psc
@itemx psc2
    Postscript (level 1 and 2, mono and color)
@item eps
@itemx eps2
@itemx epsc
@itemx epsc2
    Encapsulated postscript (level 1 and 2, mono and color)
@item tex
@itemx epslatex
@itemx epslatexstandalone
@itemx pstex
@itemx pslatex
    Generate a @LaTeX{} (or @TeX{}) file for labels, and eps/ps for
graphics.  The file produced by @code{epslatexstandalone} can be
processed directly by @LaTeX{}.  The other formats are intended to
be included in a @LaTeX{} (or @TeX{}) document.  The @code{tex} device
is the same as the @code{epslatex} device.
@item ill
@itemx aifm
    Adobe Illustrator
@item cdr
@itemx corel
    CorelDraw
@item dxf
    AutoCAD
@item emf
@itemx meta
    Microsoft Enhanced Metafile
@item fig
    XFig.  If this format is selected the additional options
@code{-textspecial} or @code{-textnormal} can be used to control
    whether the special flag should be set for the text in
    the figure (default is @code{-textnormal}). 
@item hpgl
    HP plotter language
@item mf
    Metafont
@item png
    Portable network graphics
@item jpg
@itemx jpeg
    JPEG image
@item gif
    GIF image
@item pbm
    PBMplus
@item svg
    Scalable vector graphics
@item pdf
    Portable document format
@end table

  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.

@item -d@var{gs_device}
  Additional devices are supported by Ghostscript.
Some examples are;

@table @code
@item ljet2p 
    HP LaserJet IIP
@item ljet3 
    HP LaserJet III
@item deskjet
    HP DeskJet and DeskJet Plus
@item cdj550
    HP DeskJet 550C
@item paintjet
    HP PointJet
@item pcx24b
    24-bit color PCX file format
@item ppm
    Portable Pixel Map file format
@end table

  For a complete list, type `system ("gs -h")' to see what formats
and devices are available.

  When the ghostscript is sent to a printer the size is determined
by the figure's "papersize" property.  When the ghostscript output 
is sent to a file the size is determined by the figure's
"paperposition" property.

@itemx -r@var{NUM}
  Resolution of bitmaps in pixels per inch.  For both metafiles and 
SVG the default is the screen resolution, for other it is 150 dpi.
To specify screen resolution, use "-r0".

@item -tight
  Forces a tight bounding box for eps-files.  Since the ghostscript
devices are conversion of an eps-file, this option works the those
devices as well.

@itemx -S@var{xsize},@var{ysize}
  Plot size in pixels for EMF, GIF, JPEG, PBM, PNG and SVG.  If
using the command form of the print function, you must quote the
@var{xsize},@var{ysize} option.  For example, by writing
@w{@code{"-S640,480"}}.  The size defaults to that specified by the
figure's paperposition property.

@item -F@var{fontname}
@itemx -F@var{fontname}:@var{size}
@itemx -F:@var{size}
@var{fontname} set the postscript font (for use with postscript,
aifm, corel and fig).  By default, 'Helvetica' is set for PS/Aifm,
and 'SwitzerlandLight' for Corel.  It can also be 'Times-Roman'.
@var{size} is given in points.  @var{fontname} is ignored for the
fig device.
@end table

The filename and options can be given in any order.
@end deftypefn


@c ./plot/orient.m
@anchor{doc-orient}
@deftypefn {Function File} {} orient (@var{orientation})
Set the default print orientation.  Valid values for
@var{orientation} include @code{"landscape"}, @code{"portrait"}, 
and @code{"tall"}.

The @code{"tall"} option sets the orientation to portait and fills
the page with the plot, while leaving a 0.25in border.

If called with no arguments, return the default print orientation.
@end deftypefn


@node Interacting with plots
@subsection Interacting with plots

The user can select points on a plot with the @code{ginput} function or
selection the position at which to place text on the plot with the
@code{gtext} function using the mouse.

@c ./plot/ginput.m
@anchor{doc-ginput}
@deftypefn {Function File} {[@var{x}, @var{y}, @var{buttons}] =} ginput (@var{n})
Return which mouse buttons were pressed and keys were hit on the current
figure.  If @var{n} is defined, then wait for @var{n} mouse clicks
before returning.  If @var{n} is not defined, then @code{ginput} will
loop until the return key is pressed.
@end deftypefn


@c ./plot/waitforbuttonpress.m
@anchor{doc-waitforbuttonpress}
@deftypefn {Function File} {@var{b} =} waitforbuttonpress ()
Wait for button or mouse press.over a figure window.  The value of
@var{b} returns 0 if a mouse button was pressed or 1 is a key was
pressed.
@seealso{@ref{doc-ginput,,ginput}}
@end deftypefn


@c ./plot/gtext.m
@anchor{doc-gtext}
@deftypefn  {Function File} {} gtext (@var{s})
@deftypefnx {Function File} {} gtext (@{@var{s1}; @var{s2}; @dots{}@})
@deftypefnx {Function File} {} gtext (@dots{}, @var{prop}, @var{val})
Place text on the current figure using the mouse.  The text is defined
by the string @var{s}.  If @var{s} is a cell array, each element of the cell
array is written to a separate line.  Additional arguments are passed to
the underlying text object as properties.
@seealso{@ref{doc-ginput,,ginput}, @ref{doc-text,,text}}
@end deftypefn


@node Test Plotting Functions
@subsection Test Plotting Functions

The functions @code{sombrero} and @code{peaks} provide a way to check
that plotting is working.  Typing either @code{sombrero} or @code{peaks}
at the Octave prompt should display a three-dimensional plot.

@c ./plot/sombrero.m
@anchor{doc-sombrero}
@deftypefn {Function File} {} sombrero (@var{n})
Produce the familiar three-dimensional sombrero plot using @var{n}
grid lines.  If @var{n} is omitted, a value of 41 is assumed.

The function plotted is

@example
z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2))
@end example
@seealso{@ref{doc-surf,,surf}, @ref{doc-meshgrid,,meshgrid}, @ref{doc-mesh,,mesh}}
@end deftypefn


@c ./plot/peaks.m
@anchor{doc-peaks}
@deftypefn {Function File} {} peaks ()
@deftypefnx {Function File} {} peaks (@var{n})
@deftypefnx {Function File} {} peaks (@var{x}, @var{y})
@deftypefnx {Function File} {@var{z} =} peaks (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} peaks (@dots{})
Generate a function with lots of local maxima and minima.  The function
has the form

@tex
$f(x,y) = 3 (1 - x) ^ 2 e ^ {\left(-x^2 - (y+1)^2\right)} - 10 \left({x \over 5} - x^3 - y^5)\right) - {1 \over 3} e^{\left(-(x+1)^2 - y^2\right)}$
@end tex
@ifnottex
@verbatim
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)
@end verbatim
@end ifnottex

Called without a return argument, @code{peaks} plots the surface of the 
above function using @code{mesh}.  If @var{n} is a scalar, the @code{peaks}
returns the values of the above function on a @var{n}-by-@var{n} mesh over
the range @code{[-3,3]}.  The default value for @var{n} is 49.

If @var{n} is a vector, then it represents the @var{x} and @var{y} values
of the grid on which to calculate the above function.  The @var{x} and 
@var{y} values can be specified separately.
@seealso{@ref{doc-surf,,surf}, @ref{doc-mesh,,mesh}, @ref{doc-meshgrid,,meshgrid}}
@end deftypefn


@node Advanced Plotting
@section Advanced Plotting

@menu
* Graphics Objects::
* Graphics Object Properties::  
* Managing Default Properties::  
* Colors::
* Line Styles::
* Marker Styles::
* Callbacks::
* Object Groups::
* Graphics backends::
@end menu

@node Graphics Objects
@subsection Graphics Objects

Plots in Octave are constructed from the following @dfn{graphics
objects}.  Each graphics object has a set of properties that define its
appearance and may also contain links to other graphics objects.
Graphics objects are only referenced by a numeric index, or @dfn{handle}.

@table @asis
@item root figure
@cindex root figure graphics object
@cindex graphics object, root figure
The parent of all figure objects.  The index for the root figure is
defined to be 0.

@item figure
@cindex figure graphics object
@cindex graphics object, figure
A figure window.

@item axes
@cindex axes graphics object
@cindex graphics object, axes
A set of axes.  This object is a child of a figure object and may be a
parent of line, text, image, patch, or surface objects.

@item line
@cindex line graphics object
@cindex graphics object, line
A line in two or three dimensions.

@item text
@cindex text graphics object
@cindex graphics object, text
Text annotations.

@item image
@cindex image graphics object
@cindex graphics object, image
A bitmap image.

@item patch
@cindex patch graphics object
@cindex graphics object, patch
A filled polygon, currently limited to two dimensions.

@item surface
@cindex surface graphics object
@cindex graphics object, surface 
A three-dimensional surface.
@end table

To determine whether a variable is a graphics object index or a figure
index, use the functions @code{ishandle} and @code{isfigure}.

@c graphics.cc
@anchor{doc-ishandle}
@deftypefn {Built-in Function} {} ishandle (@var{h})
Return true if @var{h} is a graphics handle and false otherwise.
@end deftypefn


@c ./plot/ishghandle.m
@anchor{doc-ishghandle}
@deftypefn {Function File} {} ishghandle (@var{h})
Return true if @var{h} is a graphics handle and false otherwise.
@end deftypefn


@c ./plot/isfigure.m
@anchor{doc-isfigure}
@deftypefn {Function File} {} isfigure (@var{h})
Return true if @var{h} is a graphics handle that contains a figure
object and false otherwise.
@end deftypefn


The function @code{gcf} returns an index to the current figure object,
or creates one if none exists.  Similarly, @code{gca} returns the
current axes object, or creates one (and its parent figure object) if
none exists.

@c ./plot/gcf.m
@anchor{doc-gcf}
@deftypefn {Function File} {} gcf ()
Return the current figure handle.  If a 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,

@example
@group
fplot (@@sin, [-10, 10]);
fig = gcf ();
set (fig, "visible", "off");
@end group
@end example

@noindent
plots a sine wave, finds the handle of the current figure, and then
makes that figure invisible.  Setting the visible property of the
figure to @code{"on"} will cause it to be displayed again.
@seealso{@ref{doc-get,,get}, @ref{doc-set,,set}}
@end deftypefn


@c ./plot/gca.m
@anchor{doc-gca}
@deftypefn {Function File} {} gca ()
Return a handle to the current axis object.  If no axis object
exists, create one and return its handle.  The handle may then be
used to examine or set properties of the axes.  For example,

@example
@group
ax = gca ();
set (ax, "position", [0.5, 0.5, 0.5, 0.5]);
@end group
@end example

@noindent
creates an empty axes object, then changes its location and size in
the figure window.
@seealso{@ref{doc-get,,get}, @ref{doc-set,,set}}
@end deftypefn


The @code{get} and @code{set} functions may be used to examine and set
properties for graphics objects.  For example,

@example
@group
get (0)
    @result{} ans =
       @{
         type = root
         currentfigure = [](0x0)
         children = [](0x0)
         visible = on
			@dots{}
       @}
@end group
@end example

@noindent
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 @code{set} function.  Also, note that in this
case, the @code{currentfigure} property is empty, which indicates that
there is no current figure window.

The @code{get} function may also be used to find the value of a single
property.  For example,

@example
@group
get (gca (), "xlim")
    @result{} [ 0 1 ]
@end group
@end example

@noindent
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,

@example
set (gca (), "xlim", [-10, 10]);
@end example

@noindent
sets the range of the x-axis for the current axes object in the current
figure to @samp{[-10, 10]}.  Additionally, calling set with a graphics
object index as the only argument returns a structure containing the
default values for all the properties for the given object type.  For
example,

@example
set (gca ())
@end example

@noindent
returns a structure containing the default property values for axes
objects.

@c graphics.cc
@anchor{doc-get}
@deftypefn {Built-in Function} {} get (@var{h}, @var{p})
Return the named property @var{p} from the graphics handle @var{h}.
If @var{p} is omitted, return the complete property list for @var{h}.
If @var{h} is a vector, return a cell array including the property
values or lists respectively.
@end deftypefn


@c graphics.cc
@anchor{doc-set}
@deftypefn {Built-in Function} {} set (@var{h}, @var{p}, @var{v}, @dots{})
Set the named property value or vector @var{p} to the value @var{v}
for the graphics handle @var{h}.
@end deftypefn


@c ./plot/ancestor.m
@anchor{doc-ancestor}
@deftypefn {Function File} {@var{parent} =} ancestor (@var{h}, @var{type})
@deftypefnx {Function File} {@var{parent} =} ancestor (@var{h}, @var{type}, 'toplevel')
Return the first ancestor of handle object @var{h} whose type matches
@var{type}, where @var{type} is a character string.  If @var{type} is a
cell array of strings, return the first parent whose type matches
any of the given type strings.

If the handle object @var{h} is of type @var{type}, return @var{h}.

If @code{"toplevel"} is given as a 3rd argument, return the highest
parent in the object hierarchy that matches the condition, instead
of the first (nearest) one.
@seealso{@ref{doc-get,,get}, @ref{doc-set,,set}}
@end deftypefn


@c ./plot/allchild.m
@anchor{doc-allchild}
@deftypefn {Function File} {@var{h} =} allchild (@var{handles})
Find all children, including hidden children, of a graphics object.

This function is similar to @code{get (h, "children")}, but also
returns includes hidden objects.  If @var{handles} is a scalar,
@var{h} will be a vector.  Otherwise, @var{h} will be a cell matrix
of the same size as @var{handles} and each cell will contain a
vector of handles.
@seealso{@ref{doc-get,,get}, @ref{doc-set,,set}, @ref{doc-findall,,findall}, @ref{doc-findobj,,findobj}}
@end deftypefn


You can create axes, line, and patch objects directly using the
@code{axes}, @code{line}, and @code{patch} functions.  These objects
become children of the current axes object.

@c ./plot/axes.m
@anchor{doc-axes}
@deftypefn {Function File} {} axes ()
@deftypefnx {Function File} {} axes (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} axes (@var{h})
Create an axes object and return a handle to it.
@end deftypefn


@c ./plot/line.m
@anchor{doc-line}
@deftypefn {Function File} {} line ()
@deftypefnx {Function File} {} line (@var{x}, @var{y})
@deftypefnx {Function File} {} line (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} line (@var{x}, @var{y}, @var{z}, @var{property}, @var{value}, @dots{})
Create line object from @var{x} and @var{y} and insert in current
axes object.  Return a handle (or vector of handles) to the line
objects created.

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


@c ./plot/patch.m
@anchor{doc-patch}
@deftypefn {Function File} {} patch ()
@deftypefnx {Function File} {} patch (@var{x}, @var{y}, @var{c})
@deftypefnx {Function File} {} patch (@var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {Function File} {} patch (@var{fv})
@deftypefnx {Function File} {} patch ('Faces', @var{f}, 'Vertices', @var{v}, @dots{})
@deftypefnx {Function File} {} patch (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} patch (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} patch (@dots{})
Create patch object from @var{x} and @var{y} with color @var{c} and
insert in the current axes object.  Return handle to patch object.

For a uniform colored patch, @var{c} can be given as an RGB vector,
scalar value referring to the current colormap, or string value (for
example, "r" or "red").

If passed a structure @var{fv} contain the fields "vertices", "faces"
and optionally "facevertexcdata", create the patch based on these 
properties.
@end deftypefn


@c ./plot/fill.m
@anchor{doc-fill}
@deftypefn {Function File} {} fill (@var{x}, @var{y}, @var{c})
@deftypefnx {Function File} {} fill (@var{x1}, @var{y1}, @var{c1}, @var{x2}, @var{y2}, @var{c2})
@deftypefnx {Function File} {} fill (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} fill (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} fill (@dots{})
Create one or more filled patch objects, returning a patch object for each.
@end deftypefn


@c ./plot/surface.m
@anchor{doc-surface}
@deftypefn {Function File} {} surface (@var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {Function File} {} surface (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surface (@var{z}, @var{c})
@deftypefnx {Function File} {} surface (@var{z})
@deftypefnx {Function File} {} surface (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} surface (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} surface (@dots{})
Plot a surface graphic object given matrices @var{x}, and @var{y} from 
@code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and 
@var{y} coordinates of the surface.  If @var{x} and @var{y} are vectors,
then a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, 
columns of @var{z} correspond to different @var{x} values and rows of 
@var{z} correspond to different @var{y} values.  If @var{x} and @var{y}
are missing, they are constructed from size of the matrix @var{z}.

Any additional properties passed are assigned to the surface.
@seealso{@ref{doc-surf,,surf}, @ref{doc-mesh,,mesh}, @ref{doc-patch,,patch}, @ref{doc-line,,line}}
@end deftypefn


By default, Octave refreshes the plot window when a prompt is printed,
or when waiting for input.  To force an update at other times, call the
@code{drawnow} function.

@c graphics.cc
@anchor{doc-drawnow}
@deftypefn  {Built-in Function} {} drawnow ()
@deftypefnx {Built-in Function} {} drawnow ("expose")
@deftypefnx {Built-in Function} {} drawnow (@var{term}, @var{file}, @var{mono}, @var{debug_file})
Update figure windows and their children.  The event queue is flushed and
any callbacks generated are executed.  With the optional argument
@code{"expose"}, only graphic objects are updated and no other events or
callbacks are processed.
The third calling form of @code{drawnow} is for debugging and is
undocumented.
@end deftypefn


Only figures that are modified will be updated.  The @code{refresh}
function can also be used to force an update of the current figure, even if
it is not modified.

@c ./plot/refresh.m
@anchor{doc-refresh}
@deftypefn {Function File} {} refresh ()
@deftypefnx {Function File} {} refresh (@var{h})
Refresh a figure, forcing it to be redrawn.  Called without an
argument the current figure is redrawn, otherwise the figure pointed
to by @var{h} is redrawn.
@seealso{@ref{doc-drawnow,,drawnow}}
@end deftypefn


Normally, high-level plot functions like @code{plot} or @code{mesh} call
@code{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 @code{hold}
function.  For example,

@example
@group
hold on;
x = -10:0.1:10;
plot (x, sin (x));
plot (x, cos (x));
hold off;
@end group
@end example

@noindent
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.

@c ./plot/newplot.m
@anchor{doc-newplot}
@deftypefn {Function File} {} newplot ()
Prepare graphics engine to produce a new plot.  This function should
be called at the beginning of all high-level plotting functions.
@end deftypefn


@c ./plot/hold.m
@anchor{doc-hold}
@deftypefn  {Function File} {} hold
@deftypefnx {Function File} {} hold @var{state}
@deftypefnx {Function File} {} hold (@var{hax}, @dots{})
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.  

@table @code
@item hold on
Retain plot data and settings so that subsequent plot commands are displayed
on a single graph.

@item hold off
Clear plot and restore default graphics settings before each new plot
command.  (default).

@item hold
Toggle the current 'hold' state.
@end table

When given the additional argument @var{hax}, the hold state is modified
only for the given axis handle.

To query the current 'hold' state use the @code{ishold} function.
@seealso{@ref{doc-ishold,,ishold}, @ref{doc-cla,,cla}, @ref{doc-newplot,,newplot}, @ref{doc-clf,,clf}}
@end deftypefn


@c ./plot/ishold.m
@anchor{doc-ishold}
@deftypefn {Function File} {} ishold
Return true if the next line will be added to the current plot, or
false if the plot device will be cleared before drawing the next line.
@end deftypefn


To clear the current figure, call the @code{clf} function.  To clear the
current axis, call the @code{cla} function.  To bring the current figure
to the top of the window stack, call the @code{shg} function.  To delete
a graphics object, call @code{delete} on its index.  To close the
figure window, call the @code{close} function.

@c ./plot/clf.m
@anchor{doc-clf}
@deftypefn  {Function File} {} clf ()
@deftypefnx {Function File} {} clf ("reset")
@deftypefnx {Function File} {} clf (@var{hfig})
@deftypefnx {Function File} {} clf (@var{hfig}, "reset")
Clear the current figure window.  @code{clf} operates by deleting child
graphics objects with visible handles (@code{HandleVisibility} = on).
If @var{hfig} is specified operate on it instead of the current figure.
If the optional argument @code{"reset"} is specified, all objects including
those with hidden handles are deleted.
@seealso{@ref{doc-cla,,cla}, @ref{doc-close,,close}, @ref{doc-delete,,delete}}
@end deftypefn


@c ./plot/cla.m
@anchor{doc-cla}
@deftypefn {Function File} {} cla ()
@deftypefnx {Function File} {} cla ("reset")
@deftypefnx {Function File} {} cla (@var{hax})
@deftypefnx {Function File} {} cla (@var{hax}, "reset")
Delete the children of the current axes with visible handles.
If @var{hax} is specified and is an axes object handle, operate on it
instead of the current axes.  If the optional argument @code{"reset"}
is specified, also delete the children with hidden handles.
@seealso{@ref{doc-clf,,clf}}
@end deftypefn


@c ./plot/shg.m
@anchor{doc-shg}
@deftypefn {Function File} {} shg
Show the graph window.  Currently, this is the same as executing
@code{drawnow}.
@seealso{@ref{doc-drawnow,,drawnow}, @ref{doc-figure,,figure}}
@end deftypefn


@c ./miscellaneous/delete.m
@anchor{doc-delete}
@deftypefn  {Function File} {} delete (@var{file})
@deftypefnx {Function File} {} delete (@var{handle})
Delete the named file or graphics handle.

Deleting graphics objects is the proper way to remove
features from a plot without clearing the entire figure.
@seealso{@ref{doc-clf,,clf}, @ref{doc-cla,,cla}}
@end deftypefn


@c ./plot/close.m
@anchor{doc-close}
@deftypefn {Command} {} close
@deftypefnx {Command} {} close (@var{n})
@deftypefnx {Command} {} close all
@deftypefnx {Command} {} close all hidden
Close figure window(s) by calling the function specified by the
@code{"closerequestfcn"} property for each figure.  By default, the
function @code{closereq} is used.
@seealso{@ref{doc-closereq,,closereq}}
@end deftypefn


@c ./plot/closereq.m
@anchor{doc-closereq}
@deftypefn {Function File} {} closereq ()
Close the current figure and delete all graphics objects associated
with it.
@seealso{@ref{doc-close,,close}, @ref{doc-delete,,delete}}
@end deftypefn


@node Graphics Object Properties
@subsection Graphics Object Properties
@cindex graphics object properties

@menu
* Root Figure Properties::      
* Figure Properties::           
* Axes Properties::             
* Line Properties::             
* Text Properties::             
* Image Properties::            
* Patch Properties::            
* Surface Properties::          
* Searching Properties::
@end menu

@node Root Figure Properties
@subsubsection Root Figure Properties

@table @code
@item currentfigure
Index to graphics object for the current figure.

@c FIXME -- does this work?
@c @item visible
@c Either @code{"on"} or @code{"off"} to toggle display of figures.
@end table

@node Figure Properties
@subsubsection Figure Properties
@cindex figure properties

@table @code
@item nextplot
May be one of
@table @code
@item "new"
@item "add"
@item "replace"
@item "replacechildren"
@end table

@item closerequestfcn
Handle of function to call when a figure is closed.

@item currentaxes
Index to graphics object of current axes.

@item colormap
An N-by-3 matrix containing the color map for the current axes.

@item visible
Either @code{"on"} or @code{"off"} to toggle display of the figure.

@item paperorientation
Indicates the orientation for printing.  Either @code{"landscape"} or
@code{"portrait"}.
@end table

@node Axes Properties
@subsubsection Axes Properties
@cindex axes properties

@table @code
@item position
A vector specifying the position of the plot, excluding titles, axes and
legend.  The four elements of the vector are the coordinates of the
lower left corner and width and height of the plot, in units normalized
to the width and height of the plot window.  For example, @code{[0.2,
0.3, 0.4, 0.5]} sets the lower left corner of the axes at @math{(0.2,
0.3)} and the width and height to be 0.4 and 0.5 respectively.  See also
the @code{outerposition} property.

@item title
Index of text object for the axes title.

@item box
Either @code{"on"} or @code{"off"} to toggle display of the box around
the axes.

@item key
Either @code{"on"} or @code{"off"} to toggle display of the legend.
Note that this property is not compatible with @sc{matlab} and may be
removed in a future version of Octave.

@item keybox
Either @code{"on"} or @code{"off"} to toggle display of a box around the
legend.  Note that this property is not compatible with @sc{matlab} and
may be removed in a future version of Octave.

@item keypos
An integer from 1 to 4 specifying the position of the legend.  1
indicates upper right corner, 2 indicates upper left, 3 indicates lower
left, and 4 indicates lower right.  Note that this property is not
compatible with @sc{matlab} and may be removed in a future version of
Octave.

@item dataaspectratio
A two-element vector specifying the relative height and width of the
data displayed in the axes.  Setting @code{dataaspectratio} to @samp{1,
2]} causes the length of one unit as displayed on the y-axis to be the
same as the length of 2 units on the x-axis.  Setting
@code{dataaspectratio} also forces the @code{dataaspectratiomode}
property to be set to @code{"manual"}.

@item dataaspectratiomode
Either @code{"manual"} or @code{"auto"}.

@item xlim
@itemx ylim
@itemx zlim
@itemx clim
Two-element vectors defining the limits for the x, y, and z axes and the 
Setting one of these properties also forces the corresponding mode
property to be set to @code{"manual"}.

@item xlimmode
@itemx ylimmode
@itemx zlimmode
@itemx climmode
Either @code{"manual"} or @code{"auto"}.

@item xlabel
@itemx ylabel
@itemx zlabel
Indices to text objects for the axes labels.

@item xgrid
@itemx ygrid
@itemx zgrid
Either @code{"on"} or @code{"off"} to toggle display of grid lines.

@item xminorgrid
@itemx yminorgrid
@itemx zminorgrid
Either @code{"on"} or @code{"off"} to toggle display of minor grid lines.

@item xtick
@itemx ytick
@itemx ztick
Setting one of these properties also forces the corresponding mode
property to be set to @code{"manual"}.

@item xtickmode
@itemx ytickmode
@itemx ztickmode
Either @code{"manual"} or @code{"auto"}.

@item xticklabel
@itemx yticklabel
@itemx zticklabel
Setting one of these properties also forces the corresponding mode
property to be set to @code{"manual"}.

@item xticklabelmode
@itemx yticklabelmode
@itemx zticklabelmode
Either @code{"manual"} or @code{"auto"}.

@item xscale
@itemx yscale
@itemx zscale
Either @code{"linear"} or @code{"log"}.

@item xdir
@itemx ydir
@itemx zdir
Either @code{"forward"} or @code{"reverse"}.

@item xaxislocation
@itemx yaxislocation
Either @code{"top"} or @code{"bottom"} for the x-axis and @code{"left"}
or @code{"right"} for the y-axis.

@item view
A three element vector specifying the view point for three-dimensional plots.

@item visible
Either @code{"on"} or @code{"off"} to toggle display of the axes.

@item nextplot
May be one of
@table @code
@item "new"
@item "add"
@item "replace"
@item "replacechildren"
@end table

@item outerposition
A vector specifying the position of the plot, including titles, axes and
legend.  The four elements of the vector are the coordinates of the
lower left corner and width and height of the plot, in units normalized
to the width and height of the plot window.  For example, @code{[0.2,
0.3, 0.4, 0.5]} sets the lower left corner of the axes at @math{(0.2,
0.3)} and the width and height to be 0.4 and 0.5 respectively.  See also
the @code{position} property.
@end table

@node Line Properties
@subsubsection Line Properties
@cindex line properties

@table @code
@itemx xdata
@itemx ydata
@itemx zdata
@itemx ldata
@itemx udata
@itemx xldata
@itemx xudata
The data to be plotted.  The @code{ldata} and @code{udata} elements are
for errorbars in the y direction, and the @code{xldata} and @code{xudata}
elements are for errorbars in the x direction.

@item color
The RGB color of the line, or a color name.  @xref{Colors}.

@item linestyle
@itemx linewidth
@xref{Line Styles}.

@item marker
@item markeredgecolor
@item markerfacecolor
@item markersize
@xref{Marker Styles}.

@item keylabel
The text of the legend entry corresponding to this line.  Note that this
property is not compatible with @sc{matlab} and may be removed in a
future version of Octave.
@end table

@node Text Properties
@subsubsection Text Properties
@cindex text properties

@table @code
@item string
The character string contained by the text object.

@item units
May be @code{"normalized"} or @code{"graph"}.

@item position
The coordinates of the text object.

@item rotation
The angle of rotation for the displayed text, measured in degrees.

@item horizontalalignment
May be @code{"left"}, @code{"center"}, or @code{"right"}.

@item color
The color of the text.  @xref{Colors}.

@item fontname
The font used for the text.

@item fontsize
The size of the font, in points to use.

@item fontangle
Flag whether the font is italic or normal.  Valid values are 'normal',
'italic' and 'oblique'.

@item fontweight
Flag whether the font is bold, etc.  Valid values are 'normal', 'bold',
'demi' or 'light'.

@item interpreter
Determines how the text is rendered.  Valid values are 'none', 'tex' or
'latex'.
@end table

All text objects, including titles, labels, legends, and text, include
the property 'interpreter', this property determines the manner in which
special control sequences in the text are rendered.  If the interpreter
is set to 'none', then no rendering occurs.  At this point the 'latex'
option is not implemented and so the 'latex' interpreter also does not
interpret the text.

The 'tex' option implements a subset of @sc{TeX} functionality in the
rendering of the text.  This allows the insertion of special characters
such as Greek or mathematical symbols within the text.  The special
characters are also inserted with a code starting with the back-slash
(\) character, as in the table @ref{tab:extended}. 

In addition, the formatting of the text can be changed within the string
with the codes 

@multitable @columnfractions .2 .2 .6 .2
@item @tab \bf @tab Bold font @tab
@item @tab \it @tab Italic font @tab
@item @tab \sl @tab Oblique Font @tab
@item @tab \rm @tab Normal font @tab
@end multitable

These are be used in conjunction with the @{ and @} characters to limit
the change in the font to part of the string.  For example

@example
xlabel ('@{\bf H@} = a @{\bf V@}')
@end example

where the character 'a' will not appear in a bold font.  Note that to
avoid having Octave interpret the backslash characters in the strings,
the strings should be in single quotes.

It is also possible to change the fontname and size within the text 

@multitable @columnfractions .1 .4 .6 .1
@item @tab \fontname@{@var{fontname}@} @tab Specify the font to use @tab
@item @tab \fontsize@{@var{size}@} @tab Specify the size of the font to
use @tab
@end multitable

Finally, the superscript 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 super- or
sub-scripted.  Without the @{ @} pair, only the character immediately
following the '^' or '_' is super- or sub-scripted.

@float Table,tab:extended
@tex
\vskip 6pt
{\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt 
\halign{
\vrule height2.0ex depth1.ex width 0.6pt #\tabskip=0.3em &
# \hfil & \vrule # & # \hfil & # \vrule &
# \hfil & \vrule # & # \hfil & # \vrule &
# \hfil & \vrule # & # \hfil & # \vrule 
width 0.6pt \tabskip=0pt\cr
\noalign{\hrule height 0.6pt}
& Code && Sym && Code && Sym && Code && Sym &\cr
\noalign{\hrule}
& $\backslash$forall    && $\forall$ 
&& $\backslash$exists   && $\exists$ 
&& $\backslash$ni       && $\ni$       &\cr
& $\backslash$cong      && $\cong$ 
&& $\backslash$Delta    && $\Delta$ 
&& $\backslash$Phi      && $\Phi$      &\cr
& $\backslash$Gamma     && $\Gamma$ 
&& $\backslash$vartheta && $\vartheta$ 
&& $\backslash$Lambda   && $\Lambda$   &\cr
& $\backslash$Pi        && $\Pi$ 
&& $\backslash$Theta    && $\Theta$ 
&& $\backslash$Sigma    && $\Sigma$    &\cr
& $\backslash$varsigma  && $\varsigma$ 
&& $\backslash$Omega    && $\Omega$ 
&& $\backslash$Xi       && $\Xi$       &\cr
& $\backslash$Psi       && $\Psi$ 
&& $\backslash$perp     && $\perp$ 
&& $\backslash$alpha    && $\alpha$    &\cr
& $\backslash$beta      && $\beta$ 
&& $\backslash$chi      && $\chi$ 
&& $\backslash$delta    && $\delta$    &\cr
& $\backslash$epsilon   && $\epsilon$ 
&& $\backslash$phi      && $\phi$ 
&& $\backslash$gamma    && $\gamma$    &\cr
& $\backslash$eta       && $\eta$ 
&& $\backslash$iota     && $\iota$ 
&& $\backslash$varphi   && $\varphi$   &\cr
& $\backslash$kappa     && $\kappa$ 
&& $\backslash$lambda   && $\lambda$ 
&& $\backslash$mu       && $\mu$       &\cr
& $\backslash$nu        && $\nu$ 
&& $\backslash$o        && $\o$ 
&& $\backslash$pi       && $\pi$       &\cr
& $\backslash$theta     && $\theta$ 
&& $\backslash$rho      && $\rho$ 
&& $\backslash$sigma    && $\sigma$    &\cr
& $\backslash$tau       && $\tau$
&& $\backslash$upsilon  && $\upsilon$ 
&& $\backslash$varpi    && $\varpi$    &\cr
& $\backslash$omega     && $\omega$ 
&& $\backslash$xi       && $\xi$ 
&& $\backslash$psi      && $\psi$      &\cr
& $\backslash$zeta      && $\zeta$ 
&& $\backslash$sim      && $\sim$ 
&& $\backslash$Upsilon  && $\Upsilon$  &\cr
& $\backslash$prime     && $\prime$ 
&& $\backslash$leq      && $\leq$ 
&& $\backslash$infty    && $\infty$    &\cr
& $\backslash$clubsuit  && $\clubsuit$ 
&& $\backslash$diamondsuit    && $\diamondsuit$ 
&& $\backslash$heartsuit      && $\heartsuit$     &\cr
& $\backslash$spadesuit       && $\spadesuit$ 
&& $\backslash$leftrightarrow && $\leftrightarrow$ 
&& $\backslash$leftarrow      && $\leftarrow$     &\cr
& $\backslash$uparrow         && $\uparrow$ 
&& $\backslash$rightarrow     && $\rightarrow$ 
&& $\backslash$downarrow      && $\downarrow$     &\cr
& $\backslash$circ      && $\circ$ 
&& $\backslash$pm       && $\pm$ 
&& $\backslash$geq      && $\geq$      &\cr
& $\backslash$times     && $\times$ 
&& $\backslash$propto   && $\propto$ 
&& $\backslash$partial  && $\partial$  &\cr
& $\backslash$bullet    && $\bullet$
&& $\backslash$div      && $\div$ 
&& $\backslash$neq      && $\neq$      &\cr
& $\backslash$equiv     && $\equiv$ 
&& $\backslash$approx   && $\approx$ 
&& $\backslash$ldots    && $\ldots$ &\cr
& $\backslash$mid       && $\mid$ 
&& $\backslash$aleph    && $\aleph$ 
&& $\backslash$Im       && $\Im$ &\cr
& $\backslash$Re        && $\Re$ 
&& $\backslash$wp       && $\wp$ 
&& $\backslash$otimes   && $\otimes$ &\cr
& $\backslash$oplus     && $\oplus$ 
&& $\backslash$oslash   && $\oslash$ 
&& $\backslash$cap      && $\cap$ &\cr
& $\backslash$cup       && $\cup$ 
&& $\backslash$supset   && $\supset$ 
&& $\backslash$supseteq && $\supseteq$ &\cr
& $\backslash$subset    && $\subset$ 
&& $\backslash$subseteq && $\subseteq$ 
&& $\backslash$in       && $\in$ &\cr
& $\backslash$notin     && $\notin$
&& $\backslash$angle    && $\angle$
&& $\backslash$bigtriangledown && $\bigtriangledown$ &\cr
& $\backslash$langle    && $\langle$ 
&& $\backslash$rangle   && $\rangle$ 
&& $\backslash$nabla    && $\nabla$    &\cr
& $\backslash$prod      && $\prod$
&& $\backslash$surd     && $\surd$ 
&& $\backslash$cdot     && $\cdot$     &\cr
& $\backslash$neg       && $\neg$ 
&& $\backslash$wedge    && $\wedge$ 
&& $\backslash$vee      && $\vee$      &\cr
& $\backslash$Leftrightarrow && $\Leftrightarrow$
&& $\backslash$Leftarrow     && $\Leftarrow$
&& $\backslash$Uparrow       && $\Uparrow$           &\cr
& $\backslash$Rightarrow     && $\Rightarrow$
&& $\backslash$Downarrow     && $\Downarrow$
&& $\backslash$diamond  && $\diamond$  &\cr
& $\backslash$copyright && $\copyright$ 
&& $\backslash$rfloor   && $\rfloor$ 
&& $\backslash$lceil    && $\lceil$    &\cr
& $\backslash$lfloor    && $\lfloor$ 
&& $\backslash$rceil    && $\rceil$ 
&& $\backslash$int      && $\int$      &\cr
\noalign{\hrule height 0.6pt}
}}\hfill}}
@end tex
@ifnottex
@multitable @columnfractions .125 .25 .25 .25 .125
@item @tab  \forall     @tab  \exists     @tab  \ni      @tab
@item @tab  \cong       @tab  \Delta      @tab  \Phi     @tab
@item @tab  \Gamma      @tab  \vartheta   @tab  \Lambda  @tab
@item @tab  \Pi         @tab  \Theta      @tab  \Sigma   @tab
@item @tab  \varsigma   @tab  \Omega      @tab  \Xi      @tab
@item @tab  \Psi        @tab  \perp       @tab  \alpha   @tab
@item @tab  \beta       @tab  \chi        @tab  \delta   @tab  
@item @tab  \epsilon    @tab  \phi        @tab  \gamma   @tab
@item @tab  \eta        @tab  \iota       @tab  \varphi  @tab
@item @tab  \kappa      @tab  \lambda     @tab  \mu      @tab 
@item @tab  \nu         @tab  \o          @tab  \pi      @tab
@item @tab  \theta      @tab  \rho        @tab  \sigma   @tab 
@item @tab  \tau        @tab  \upsilon    @tab  \varpi   @tab
@item @tab  \omega      @tab  \xi         @tab  \psi     @tab 
@item @tab  \zeta       @tab  \sim        @tab  \Upsilon @tab
@item @tab  \prime      @tab  \leq        @tab  \infty   @tab
@item @tab  \clubsuit   @tab  \diamondsuit    @tab  \heartsuit  @tab
@item @tab  \spadesuit  @tab  \leftrightarrow @tab  \leftarrow  @tab 
@item @tab  \uparrow    @tab  \rightarrow @tab  \downarrow @tab 
@item @tab  \circ       @tab \pm          @tab  \geq     @tab 
@item @tab  \times      @tab  \propto     @tab  \partial @tab
@item @tab  \bullet     @tab \div         @tab  \neq     @tab 
@item @tab  \equiv      @tab  \approx     @tab  \ldots   @tab 
@item @tab  \mid        @tab  \aleph      @tab  \Im      @tab 
@item @tab  \Re         @tab \wp          @tab  \otimes  @tab
@item @tab  \oplus      @tab \oslash      @tab  \cap     @tab 
@item @tab  \cup        @tab   \supset    @tab  \supseteq @tab 
@item @tab  \subset     @tab \subseteq    @tab  \in      @tab 
@item @tab  \notin      @tab \angle       @tab  \bigrightriangledown @tab
@item @tab  \langle     @tab  \rangle     @tab  \nabla   @tab
@item @tab  \prod       @tab \surd        @tab  \cdot    @tab 
@item @tab  \neg        @tab  \wedge      @tab \vee      @tab 
@item @tab  \Leftrightarrow @tab \Leftarrow @tab \Uparrow @tab
@item @tab  \Rightarrow @tab \Downarrow   @tab \diamond  @tab
@item @tab  \copyright  @tab  \lfloor     @tab  \lceil   @tab 
@item @tab  \rfloor     @tab  \rceil      @tab  \int     @tab 
@end multitable
@end ifnottex
@caption{Available special characters in @sc{TeX} mode}
@end float

A complete example showing the capabilities of the extended text is

@example
@group
x = 0:0.01:3;
plot(x,erf(x));
hold on;
plot(x,x,"r");
axis([0, 3, 0, 1]);
text(0.65, 0.6175, strcat('\leftarrow x = @{2/\surd\pi',
' @{\fontsize@{16@}\int_@{\fontsize@{8@}0@}^@{\fontsize@{8@}x@}@}',
' e^@{-t^2@} dt@} = 0.6175'))
@end group
@end example

@ifnotinfo
@noindent
The result of which can be seen in @ref{fig:extendedtext}

@float Figure,fig:extendedtext
@center @image{extended,4in}
@caption{Example of inclusion of text with the @sc{TeX} interpreter}
@end float
@end ifnotinfo

@node Image Properties
@subsubsection Image Properties
@cindex image properties

@table @code
@item cdata
The data for the image.  Each pixel of the image corresponds to an
element of @code{cdata}.  The value of an element of @code{cdata}
specifies the row-index into the colormap of the axes object containing
the image.  The color value found in the color map for the given index
determines the color of the pixel.

@item xdata
@itemx ydata
Two-element vectors specifying the range of the x- and y- coordinates for
the image.
@end table

@node Patch Properties
@subsubsection Patch Properties
@cindex patch properties

@table @code
@item cdata
@itemx xdata
@itemx ydata
@itemx zdata
Data defining the patch object.

@item facecolor
The fill color of the patch.  @xref{Colors}.

@item facealpha
A number in the range [0, 1] indicating the transparency of the patch.

@item edgecolor
The color of the line defining the patch.  @xref{Colors}.

@item linestyle
@itemx linewidth
@xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
@xref{Marker Styles}.
@end table

@node Surface Properties
@subsubsection Surface Properties
@cindex surface properties

@table @code
@item xdata
@itemx ydata
@itemx zdata
The data determining the surface.  The @code{xdata} and @code{ydata}
elements are vectors and @code{zdata} must be a matrix.

@item keylabel
The text of the legend entry corresponding to this surface.  Note that
this property is not compatible with @sc{matlab} and may be removed in a
future version of Octave.
@end table

@node Searching Properties
@subsubsection Searching Properties

@c ./plot/findobj.m
@anchor{doc-findobj}
@deftypefn {Function File} {@var{h} =} findobj ()
@deftypefnx {Function File} {@var{h} =} findobj (@var{prop_name}, @var{prop_value})
@deftypefnx {Function File} {@var{h} =} findobj ('-property', @var{prop_name})
@deftypefnx {Function File} {@var{h} =} findobj ('-regexp', @var{prop_name}, @var{pattern})
@deftypefnx {Function File} {@var{h} =} findobj ('flat', @dots{})
@deftypefnx {Function File} {@var{h} =} findobj (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} findobj (@var{h}, '-depth', @var{d}, @dots{})
Find object with specified property values.  The simplest form is

@example
findobj (@var{prop_name}, @var{prop_Value})
@end example

@noindent
which returns all of the handles to the objects with the name 
@var{prop_name} and the name @var{prop_Value}.  The search can be limited
to a particular object or set of objects and their descendants by 
passing a handle or set of handles @var{h} as the first argument to 
@code{findobj}.

The depth of hierarchy of objects to which to search to can be limited
with the '-depth' argument.  To limit the number depth of the hierarchy
to search to @var{d} generations of children, and example is

@example
findobj (@var{h}, '-depth', @var{d}, @var{prop_Name}, @var{prop_Value})
@end example

Specifying a depth @var{d} of 0, limits the search to the set of object
passed in @var{h}.  A depth @var{d} of 0 is equivalent to the '-flat'
argument. 

A specified logical operator may be applied to the pairs of @var{prop_Name}
and @var{prop_Value}.  The supported logical operators are '-and', '-or', 
'-xor', '-not'.

The objects may also be matched by comparing a regular expression to the 
property values, where property values that match @code{regexp 
(@var{prop_Value}, @var{pattern})} are returned.  Finally, objects may be 
matched by property name only, using the '-property' option.
@seealso{@ref{doc-get,,get}, @ref{doc-set,,set}}
@end deftypefn


@c ./plot/findall.m
@anchor{doc-findall}
@deftypefn {Function File} {@var{h} =} findall ()
@deftypefnx {Function File} {@var{h} =} findall (@var{prop_name}, @var{prop_value})
@deftypefnx {Function File} {@var{h} =} findall (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} findall (@var{h}, "-depth", @var{d}, @dots{})
Find object with specified property values including hidden handles.

This function performs the same function as @code{findobj}, but it
includes hidden objects in its search.  For full documentation, see
@code{findobj}.
@seealso{@ref{doc-get,,get}, @ref{doc-set,,set}, @ref{doc-findobj,,findobj}, @ref{doc-allchild,,allchild}}
@end deftypefn



@node Managing Default Properties
@subsection Managing Default Properties
@cindex default graphics properties
@cindex graphics properties, default

Object properties have two classes of default values, @dfn{factory
defaults} (the initial values) and @dfn{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.  For example,

@example
set (0, "defaultlinecolor", "green");
@end example

@noindent
sets the default line color for all objects.  The rule for constructing
the property name to set a default value is

@example
default + @var{object-type} + @var{property-name}
@end example

This rule can lead to some strange looking names, for example
@code{defaultlinelinewidth"} specifies the default @code{linewidth}
property for @code{line} objects.

The example above used the root figure object, 0, 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,

@example
@group
subplot (2, 1, 1);
set (0, "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));
@end group
@end example

@noindent
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 @code{"remove"}.  For example,

@example
set (gca (), "defaultlinecolor", "remove");
@end example

@noindent
removes the user-defined default line color setting from the current axes
object.

Getting the @code{"default"} property of an object returns a list of
user-defined defaults set for the object.  For example,

@example
get (gca (), "default");
@end example

@noindent
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

@example
get (0, "factory");
@end example

@noindent
returns a list of factory defaults.

@node Colors
@subsection Colors
@cindex graphics colors
@cindex colors, graphics

Colors may be specified as RGB triplets with values ranging from zero to
one, or by name.  Recognized color names include @code{"blue"},
@code{"black"}, @code{"cyan"}, @code{"green"}, @code{"magenta"},
@code{"red"}, @code{"white"}, and @code{"yellow"}.

@node Line Styles
@subsection Line Styles
@cindex line styles, graphics
@cindex graphics line styles

Line styles are specified by the following properties:

@table @code
@item linestyle
May be one of
@table @code
@item "-"
Solid lines.
@item "--"
Dashed lines.
@item ":"
Points.
@item "-."
A dash-dot line.
@end table

@item 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.
@end table

@node Marker Styles
@subsection Marker Styles
@cindex graphics marker styles
@cindex marker styles, graphics

Marker styles are specified by the following properties:
@table @code
@item marker
A character indicating a plot marker to be place at each data point, or
@code{"none"}, meaning no markers should be displayed.

@itemx markeredgecolor
The color of the edge around the marker, or @code{"auto"}, meaning that
the edge color is the same as the face color.  @xref{Colors}.

@itemx markerfacecolor
The color of the marker, or @code{"none"} to indicate that the marker
should not be filled.  @xref{Colors}.

@itemx 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.
@end table

@node Callbacks
@subsection Callbacks
@cindex callbacks

Callback functions can be associated with graphics objects and triggered
after certain events occur.  The basic structure of all callback function
is 

@example
@group
function mycallback (src, data)
@dots{}
endfunction
@end group
@end example

where @code{src} gives a handle to the source of the callback, and
@code{code} gives some event specific data.  This can then be associated
with an object either at the objects creation or later with the
@code{set} function.  For example

@example
plot (x, "DeleteFcn", @@(s, e) disp("Window Deleted"))
@end example

@noindent
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 2 default arguments.  For example

@example
@group
plot (x, "DeleteFcn", @{@@mycallback, "1"@})
@dots{}
function mycallback (src, data, a1)
  fprintf ("Closing plot %d\n", a1);
endfunction
@end group
@end example

The basic callback functions that are available for all graphics objects
are

@itemize @bullet
@item CreateFcn
This is the callback that is 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 @code{CreateFcn} later with
the @code{set} function will never be executed.

@item DeleteFcn
This is the callback that is called at the moment an object is deleted.

@item ButtonDownFcn
This is the callback that is called if a mouse button is pressed while
the pointer is over this object.  Note, that the gnuplot interface does
not respect this callback.
@end itemize

The object and figure that the event occurred in that resulted in the
callback being called can be found with the @code{gcbo} and @code{gcbf}
functions.

@c ./plot/gcbo.m
@anchor{doc-gcbo}
@deftypefn {Function File} {@var{h} =} gcbo ()
@deftypefnx {Function File} {[@var{h}, @var{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".

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

@seealso{@ref{doc-gcf,,gcf}, @ref{doc-gca,,gca}, @ref{doc-gcbf,,gcbf}}
@end deftypefn


@c ./plot/gcbf.m
@anchor{doc-gcbf}
@deftypefn {Function File} {@var{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.

@seealso{@ref{doc-gcf,,gcf}, @ref{doc-gca,,gca}, @ref{doc-gcbo,,gcbo}}
@end deftypefn


Callbacks can equally be added to properties with the @code{addlistener}
function described below.

@node Object Groups
@subsection Object Groups
@cindex object groups

A number of Octave high level plot functions return groups of other
graphics objects or they return graphics objects that are 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 @code{hggroup}

@c ./plot/hggroup.m
@anchor{doc-hggroup}
@deftypefn {Function File} {} hggroup ()
@deftypefnx {Function File} {} hggroup (@var{h})
@deftypefnx {Function File} {} hggroup (@dots{}, @var{property}, @var{value}, @dots{})
Create group object with parent @var{h}.  If no parent is specified,
the group is created in the current axes.  Return the handle of the
group object created.

Multiple property-value pairs may be specified for the group, but they
must appear in pairs.
@end deftypefn


For example a simple use of a @code{hggroup} might be

@example
@group
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");
@end group
@end example

@noindent
which groups the two plots into a single object and controls their
visibility directly.  The default properties of an @code{hggroup} are
the same as the set of common properties for the other graphics
objects.  Additional properties can be added with the @code{addproperty}
function. 

@c graphics.cc
@anchor{doc-addproperty}
@deftypefn {Built-in Function} {} addproperty (@var{name}, @var{h}, @var{type}, [@var{arg}, @dots{}])
Create a new property named @var{name} in graphics object @var{h}.
@var{type} determines the type of the property to create.  @var{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:

@table @code
@item string
A string property.  @var{arg} contains the default string value.
@item any
An un-typed property.  This kind of property can hold any octave
value.  @var{args} contains the default value.
@item 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.
@item boolean
A boolean property.  This property type is equivalent to a radio
property with "on|off" as accepted values.  @var{arg} contains
the default property value.
@item double
A scalar double property.  @var{arg} contains the default value.
@item handle
A handle property.  This kind of property holds the handle of a
graphics object.  @var{arg} contains the default handle value.
When no default value is given, the property is initialized to
the empty matrix.
@item data
A data (matrix) property.  @var{arg} contains the default data
value.  When no default value is given, the data is initialized to
the empty matrix.
@item color
A color property.  @var{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).
@end table

@var{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@dots{}).  This allows to clone an existing
property into the graphics object @var{h}.

Examples:

@example
@group
addproperty ("my_property", gcf, "string", "a string value");
addproperty ("my_radio", gcf, "radio", "val_1|val_2|@{val_3@}");
addproperty ("my_style", gcf, "linelinestyle", "--");
@end group
@end example

@end deftypefn


Once a property in added to an @code{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 @code{addlistener} function is used to define a
callback function that is executed when the property is altered.

@c graphics.cc
@anchor{doc-addlistener}
@deftypefn {Built-in Function} {} addlistener (@var{h}, @var{prop}, @var{fcn})
Register @var{fcn} as listener for the property @var{prop} of the graphics
object @var{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.

@var{prop} must be a string naming a valid property in @var{h}.

@var{fcn} can be a function handle, a string or a cell array whose first
element is a function handle.  If @var{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 @var{fcn}
is a string, it must be any valid octave expression.  If @var{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:

@example
@group
function my_listener (h, dummy, p1)
  fprintf ("my_listener called with p1=%s\n", p1);
endfunction

addlistener (gcf, "position", @{@@my_listener, "my string"@})
@end group
@end example

@end deftypefn


@c graphics.cc
@anchor{doc-dellistener}
@deftypefn {Built-in Function} {} dellistener (@var{h}, @var{prop}, @var{fcn})
Remove the registration of @var{fcn} as a listener for the property
@var{prop} of the graphics object @var{h}.  The function @var{fcn} must
be the same variable (not just the same value), as was passed to the
original call to @code{addlistener}.

If @var{fcn} is not defined then all listener functions of @var{prop}
are removed.

Example:

@example
@group
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);
@end group
@end example

@end deftypefn


An example of the use of these two functions might be

@example
@group
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
@end group
@end example

@noindent
that adds a @code{linestyle} property to the @code{hggroup} and
propagating any changes its value to the children of the group.  The
@code{linkprop} function can be used to simplify the above to be

@example
@group
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"); 
@end group
@end example

@c ./plot/linkprop.m
@anchor{doc-linkprop}
@deftypefn {Function File} {@var{hlink} =} linkprop (@var{h}, @var{prop})
Links graphics object properties, such that a change in one is
propagated to the others.  The properties to link are given as a
string of cell string array by @var{prop} and the objects containing
these properties by the handle array @var{h}.

An example of the use of linkprops is

@example
@group
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", "--");
@end group
@end example

@end deftypefn


These capabilities are used in a number of basic graphics objects. 
The @code{hggroup} objects created by the functions of Octave contain
one or more graphics object and are used to:

@itemize @bullet
@item group together multiple graphics objects,
@item create linked properties between different graphics objects, and
@item to hide the nominal user data, from the actual data of the objects.
@end itemize

@noindent
For example the @code{stem} function creates a stem series where each
@code{hggroup} of the stem series contains two line objects representing
the body and head of the stem.  The @code{ydata} property of the
@code{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

@example
@group
h = stem (1:4)
get (h, "xdata")
@result{} [  1   2   3   4]'
get (get (h, "children")(1), "xdata")
@result{} [  1   1 NaN   2   2 NaN   3   3 NaN   4   4 NaN]'
@end group
@end example

@noindent
shows the difference between the @code{xdata} of the @code{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 @code{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 @code{bar} or @code{stem} functions is a line object, whose length
and position are automatically adjusted, based on changes to the
corresponding hggroup elements.

@menu
* Data sources in object groups::
* Area series::
* Bar series::
* Contour groups::
* Error bar series::
* Line series::
* Quiver group::
* Scatter group::
* Stair group::
* Stem Series::
* Surface group::
@end menu

@node Data sources in object groups
@subsubsection Data sources in object groups
@cindex 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 @code{refreshdata}
function is called. 

@c ./plot/refreshdata.m
@anchor{doc-refreshdata}
@deftypefn  {Function File} {} refreshdata ()
@deftypefnx {Function File} {} refreshdata (@var{h})
@deftypefnx {Function File} {} refreshdata (@var{h}, @var{workspace})
Evaluate any @samp{datasource} properties of the current figure and update
the plot if the corresponding data has changed.  If called with one or more
arguments @var{h} is a scalar or array of figure handles to refresh.  The
optional second argument @var{workspace} can take the following values.

@table @code
@item "base"
Evaluate the datasource properties in the base workspace.  (default).
@item "caller"
Evaluate the datasource properties in the workspace of the function
that called @code{refreshdata}.
@end table

An example of the use of @code{refreshdata} is:

@example
@group
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
@end group
@end example
@end deftypefn


@anchor{doc-linkdata}
@c add the description of the linkdata function here when it is written
@c remove the explicit anchor when you add the corresponding @DOCSTRING
@c command

@node Area series
@subsubsection Area series
@cindex series objects
@cindex area series

Area series objects are created by the @code{area} function.  Each of the
@code{hggroup} elements contains a single patch object.  The properties
of the area series are

@table @code
@item basevalue
The value where the base of the area plot is drawn.

@item linewidth
@itemx linestyle
The line width and style of the edge of the patch objects making up the
areas.  @xref{Line Styles}.

@item edgecolor
@itemx facecolor
The line and fill color of the patch objects making up the areas.  @xref{Colors}.

@item xdata
@itemx ydata
The x and y coordinates of the original columns of the data passed to
@code{area} prior to the cumulative summation used in the @code{area}
function. 

@item xdatasource
@itemx ydatasource
Data source variables.
@end table

@node Bar series
@subsubsection Bar series
@cindex series objects
@cindex bar series

Bar series objects are created by the @code{bar} or @code{barh}
functions.  Each @code{hggroup} element contains a single patch object. 
The properties of the bar series are

@table @code
@item showbaseline
@itemx baseline
@itemx basevalue
The property @code{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 @code{baseline} property and
the y-value of the baseline by the @code{basevalue} property. 

Changes to any of these property 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.

@item barwidth
@itemx barlayout
@itemx horizontal
The property @code{barwidth} is the width of the bar corresponding to
the @var{width} variable passed to @code{bar} or @var{barh}.  Whether the
bar series is "grouped" or "stacked" is determined by the
@code{barlayout} property and whether the bars are horizontal or
vertical by the @code{horizontal} property.

Changes to any of these property are propagated to the other members of
the bar series.

@item linewidth
@itemx linestyle
The line width and style of the edge of the patch objects making up the
bars.  @xref{Line Styles}.

@item edgecolor
@itemx facecolor
The line and fill color of the patch objects making up the bars.  @xref{Colors}.

@item xdata
The nominal x positions of the bars.  Changes in this property and
propagated to the other members of the bar series. 

@item ydata
The y value of the bars in the @code{hggroup}.

@item xdatasource
@itemx ydatasource
Data source variables.
@end table

@node Contour groups
@subsubsection Contour groups
@cindex series objects
@cindex contour series

Contour group objects are created by the @code{contour}, @code{contourf}
and @code{contour3} functions.  The are equally one of the handles returned
by the @code{surfc} and @code{meshc} functions.  The properties of the contour
group are

@table @code
@item contourmatrix
A read only property that contains the data return by @code{contourc} used to
create the contours of the plot.

@item fill
A radio property that can have the values "on" or "off" that flags whether the
contours to plot are to be filled.

@item zlevelmode
@itemx zlevel
The radio property @code{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 @code{zlevel}
property.

@item levellistmode
@itemx levellist
@itemx levelstepmode
@itemx levelstep
If @code{levellistmode} is "manual", then the levels at which to plot the 
contours is determined by @code{levellist}.  If @code{levellistmode} is
set to "auto", then the distance between contours is determined by 
@code{levelstep}.  If both @code{levellistmode} and @code{levelstepmode}
are set to "auto", then there are assumed to be 10 equal spaced contours.

@item textlistmode
@itemx textlist
@itemx textstepmode
@itemx textstep
If @code{textlistmode} is "manual", then the labelled contours 
is determined by @code{textlist}.  If @code{textlistmode} is set to 
"auto", then the distance between labelled contours is determined by 
@code{textstep}.  If both @code{textlistmode} and @code{textstepmode}
are set to "auto", then there are assumed to be 10 equal spaced 
labelled contours.

@item showtext
Flag whether the contour labels are shown or not.

@item labelspacing
The distance between labels on a single contour in points.

@item linewidth
@item linestyle
@item linecolor
The properties of the contour lines.  The properties @code{linewidth} and
@code{linestyle} are similar to the corresponding properties for lines.  The
property @code{linecolor} is a color property (@pxref{Colors}), that can also
have the values of "none" or "auto".  If @code{linecolor} is "none", then no
contour line is drawn.  If @code{linecolor} is "auto" then the line color is
determined by the colormap.

@item xdata
@itemx ydata
@itemx zdata
The original x, y, and z data of the contour lines.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
Data source variables.
@end table

@node Error bar series
@subsubsection Error bar series
@cindex series objects
@cindex error bar series

Error bar series are created by the @code{errorbar} function.  Each 
@code{hggroup} element contains two line objects representing the data and
the errorbars separately.  The properties of the error bar series are

@table @code
@item color
The RGB color or color name of the line objects of the error bars.  @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the line objects of the error bars.  @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
The line and fill color of the markers on the error bars.  @xref{Colors}.

@item xdata
@itemx ydata
@itemx ldata
@itemx udata
@itemx xldata
@itemx xudata
The original x, y, l, u, xl, xu data of the error bars.

@item xdatasource
@itemx ydatasource
@itemx ldatasource
@itemx udatasource
@itemx xldatasource
@itemx xudatasource
Data source variables.
@end table

@node Line series
@subsubsection Line series
@cindex series objects
@cindex line series

Line series objects are created by the @code{plot}  and @code{plot3}
functions and are of the type @code{line}.  The properties of the
line series with the ability to add data sources.

@table @code
@item color
The RGB color or color name of the line objects.  @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the line objects.  @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
The line and fill color of the markers.  @xref{Colors}.

@item xdata
@itemx ydata
@itemx zdata
The original x, y and z data.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
Data source variables.
@end table

@node Quiver group
@subsubsection Quiver group
@cindex group objects
@cindex quiver group

Quiver series objects are created by the @code{quiver} or @code{quiver3}
functions.  Each @code{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 original of the arrows.  The 
properties of the quiver series are

@table @code
@item autoscale
@itemx autoscalefactor
Flag whether the length of the arrows is scaled or defined directly from
the @var{u}, @var{v} and @var{w} data.  If the arrow length is flagged
as being scaled by the @code{autoscale} property, then the length of the
autoscaled arrow is controlled by the @code{autoscalefactor}. 

@item maxheadsize
This property controls the size of the head of the arrows in the quiver
series.  The default value is 0.2.

@item showarrowhead
Flag whether the arrow heads are displayed in the quiver plot.

@item color
The RGB color or color name of the line objects of the quiver.  @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the line objects of the quiver.  @xref{Line Styles}.

@item marker
@itemx markerfacecolor
@itemx markersize
The line and fill color of the marker objects at the original of the
arrows.  @xref{Colors}.

@item xdata
@itemx ydata
@itemx zdata
The origins of the values of the vector field.

@item udata
@itemx vdata
@itemx wdata
The values of the vector field to plot.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
@itemx udatasource
@itemx vdatasource
@itemx wdatasource
Data source variables.
@end table

@node Scatter group
@subsubsection Scatter group
@cindex group objects
@cindex scatter group

Scatter series objects are created by the @code{scatter} or @code{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

@table @code
@item linewidth
The line width of the line objects of the points.  @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
The line and fill color of the markers of the points.  @xref{Colors}.

@item xdata
@itemx ydata
@itemx zdata
The original x, y and z data of the stems.

@item cdata
The color data for the points of the plot.  Each point can have a separate
color, or a unique color can be specified.

@item sizedata
The size data for the points of the plot.  Each point can its own size or a 
unique size can be specified.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
@itemx cdatasource
@itemx sizedatasource
Data source variables.
@end table

@node Stair group
@subsubsection Stair group
@cindex group objects
@cindex stair group

Stair series objects are created by the @code{stair} function.  Each
@code{hggroup} element of the series contains a single line object as a
child representing the stair.  The properties of the stair series are

@table @code
@item color
The RGB color or color name of the line objects of the stairs.  @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the line objects of the stairs.  @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
The line and fill color of the markers on the stairs.  @xref{Colors}.

@item xdata
@itemx ydata
The original x and y data of the stairs.

@item xdatasource
@itemx ydatasource
Data source variables.
@end table

@node Stem Series
@subsubsection Stem Series
@cindex series objects
@cindex stem series

Stem series objects are created by the @code{stem} or @code{stem3}
functions.  Each @code{hggroup} element contains a single line object
as a child representing the stems.  The properties of the stem series
are

@table @code
@item showbaseline
@itemx baseline
@itemx basevalue
The property @code{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 @code{baseline}
property and the y-value (or z-value for @code{stem3}) of the baseline
by the @code{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.

@item color
The RGB color or color name of the line objects of the stems.  @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the line objects of the stems.  @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
The line and fill color of the markers on the stems.  @xref{Colors}.

@item xdata
@itemx ydata
@itemx zdata
The original x, y and z data of the stems.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
Data source variables.
@end table

@node Surface group
@subsubsection Surface group
@cindex group objects
@cindex surface group

Surface group objects are created by the @code{surf} or @code{mesh}
functions, but are equally one of the handles returned by the @code{surfc}
or @code{meshc} functions.  The surface group is of the type @code{surface}.

The properties of the surface group are

@table @code
@item edgecolor
@item facecolor
The RGB color or color name of the edges or faces of the surface.  @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the lines on the surface.  @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
The line and fill color of the markers on the surface.  @xref{Colors}.

@item xdata
@itemx ydata
@itemx zdata
@item cdata
The original x, y, z and c data.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
@itemx cdatasource
Data source variables.
@end table

@node Graphics backends
@subsection Graphics backends
@cindex graphics backends
@cindex backends, graphics

@c ./plot/backend.m
@anchor{doc-backend}
@deftypefn  {Function File} {} backend (@var{name})
@deftypefnx {Function File} {} backend (@var{hlist}, @var{name})
Change the default graphics backend to @var{name}.  If the backend is
not already loaded, it is first initialized (initialization is done
through the execution of @code{__init_@var{name}__}).

When called with a list of figure handles, @var{hlist}, the backend is
changed only for the listed figures.
@seealso{@ref{doc-available_backends,,available_backends}}
@end deftypefn


@c graphics.cc
@anchor{doc-available_backends}
@deftypefn {Built-in Function} {} available_backends ()
Return a cell array of registered graphics backends.
@end deftypefn


@menu
* Interaction with gnuplot::
@end menu

@node Interaction with gnuplot
@subsubsection Interaction with @code{gnuplot}
@cindex gnuplot interaction

@c ./plot/gnuplot_binary.m
@anchor{doc-gnuplot_binary}
@deftypefn {Loadable Function} {@var{val} =} gnuplot_binary ()
@deftypefnx {Loadable Function} {@var{old_val} =} gnuplot_binary (@var{new_val})
Query or set the name of the program invoked by the plot command.
The default value @code{\"gnuplot\"}.  @xref{Installation}.
@end deftypefn