@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996, 1997, 2007 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Plotting
@chapter Plotting

@menu
* Two-Dimensional Plotting::    
* Specialized Two-Dimensional Plots::  
* Three-Dimensional Plotting::  
* Manipulating Existing Plots::
* Plot Annotations::            
* Multiple Plots on One Page::  
* Multiple Plot Windows::       
* Printing Plots::
* Test Plotting Functions::
* Interaction with gnuplot::    
@end menu

@node Two-Dimensional Plotting
@section Two-Dimensional Plotting

The basic plotting commands are:

@cindex plotting
@cindex graphics

@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


@anchor{doc-plot}
@deftypefn {Function File} {} plot (@var{args})
This function 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{x}, @var{y}, @var{fmt}, @dots{})
@end example

@noindent
or as

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

@noindent
where @var{y}, @var{fmt}, @var{property} and @var{value} are optional,
and 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

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 ^
Set impulses plot style.

@item L
Set steps 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
Used in combination with the points or linespoints styles, set the point
style.
@end table

The color line styles have the following meanings on terminals that
support color.

@example
Number  Gnuplot colors  (lines)points style
  1       red                   *
  2       green                 +
  3       blue                  o
  4       magenta               x
  5       cyan                house
  6       brown            there exists
@end example

The @var{fmt} argument can 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.

If a @var{property} is given it must be followed by @var{value}.  The
property value pairs are applied to the lines drawn by @code{plot}.

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
t = 0:0.1:6.3;
plot (t, cos(t), "-;cos(t);", t, sin(t), "+3;sin(t);");
@end example

This will plot the cosine and sine functions and label them accordingly
in the key.
@seealso{semilogx, semilogy, loglog, polar, mesh, contour, __pltopt__
bar, stairs, errorbar, xlabel, ylabel, title, print}
@end deftypefn


@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{opts})
Create line object from @var{x} and @var{y} and insert in current
axes object.  Return handle to line object.
@end deftypefn


@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{LineSpec})
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{LineSpec} is passed to the plot
command.

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


@anchor{doc-drawnow}
@deftypefn {Function File} {} drawnow ()
Display the current graphics.
@end deftypefn


@anchor{doc-shg}
@deftypefn {Function File} {} shg

Show the graph window.  Currently, this is the same as executing
@code{drawnow}.
@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, stairs, xlabel, ylabel}
@end deftypefn


@anchor{doc-hold}
@deftypefn {Function File} {} hold @var{args}
Tell Octave to `hold' the current data on the plot when executing
subsequent plotting commands.  This allows you to execute a series of
plot commands and have all the lines end up on the same figure.  The
default is for each new plot command to clear the plot device first.
For example, the command

@example
hold on
@end example

@noindent
turns the hold state on.  An argument of @code{"off"} turns the hold
state off, and @code{hold} with no arguments toggles the current hold
state.
@end deftypefn


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


@anchor{doc-newplot}
@deftypefn {Function File} {} newplot ()
@end deftypefn


@node Specialized Two-Dimensional Plots
@section Specialized Two-Dimensional Plots

@anchor{doc-bar}
@deftypefn {Function File} {@var{h} =} bar (@var{x}, @var{y}, @var{style})
@deftypefnx {Function File} {[@var{xb}, @var{yb}] =} bar (@dots{})
Given two vectors of x-y data, @code{bar} produces a bar graph.

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 @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 'group' (the default), or 'stack'.

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

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

@noindent
and

@example
[xb, yb] = bar (x, y);
plot (xb, yb);
@end example

@noindent
are equivalent.
@seealso{hbar, plot, semilogx, semilogy, loglog, polar, mesh, contour,
stairs, xlabel, ylabel, title}
@end deftypefn


@anchor{doc-contour}
@deftypefn {Function File} {} {@var{c} =} contour (@var{z})
@deftypefnx {Function File} {} {@var{c} =} contour (@var{z}, @var{vn})
@deftypefnx {Function File} {} {@var{c} =} contour (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} {@var{c} =} contour (@var{x}, @var{y}, @var{z}, @var{vn})

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.  @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
@seealso{contourc, line, plot}
@end deftypefn


@anchor{doc-contourc}
@deftypefn {Function File} {[@var{c}, @var{lev}] =}  contourc (@var{x}, @var{y}, @var{z}, @var{vn})
Compute isolines (countour 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
@var{c} = [lev1, x1, x2, ..., levn, x1, x2, ... 
     len1, y1, y2, ..., lenn, y1, y2, ...]
@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{contour}
@end deftypefn


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

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 normalised 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{bar}
@end deftypefn


@anchor{doc-loglog}
@deftypefn {Function File} {} loglog (@var{args})
Make 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{plot, semilogy, loglog, polar, mesh, contour, bar, stairs,
xlabel, ylabel, title}
@end deftypefn


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

The optional third argument specifies the line type.
@seealso{plot, semilogx, semilogy, loglog, mesh, contour, bar,
stairs, xlabel, ylabel, title}
@end deftypefn


@anchor{doc-semilogx}
@deftypefn {Function File} {} semilogx (@var{args})
Make 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{plot, semilogy, loglog, polar, mesh, contour, bar, stairs,
xlabel, ylabel, title}
@end deftypefn


@anchor{doc-semilogy}
@deftypefn {Function File} {} semilogy (@var{args})
Make 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{plot, semilogx, loglog, polar, mesh, contour, bar, stairs,
xlabel, ylabel, title}
@end deftypefn


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

For example,
@example
x = 1:10;
stem (x);
@end example
@noindent
plots 10 stems with heights from 1 to 10;

@example
x = 1:10;
y = ones (1, length (x))*2.*x;
stem (x, y);
@end example
@noindent
plots 10 stems with heights from 2 to 20;

@example
x = 1:10;
y = ones (size (x))*2.*x;
h = stem (x, y, "b");
@end example
@noindent
plots 10 bars with heights from 2 to 20
(the color is blue, and @var{h} is a 2-by-10 array of handles in
which the first row holds the line handles and the 
the second row holds the marker handles);

@example
x = 1:10;
y = ones (size (x))*2.*x;
h = stem (x, y, "-.k");
@end example
@noindent
plots 10 stems with heights from 2 to 20
(the color is black, line style is @code{"-."}, and @var{h} is a 2-by-10
array of handles in which the first row holds the line handles and
the second rows holds the marker handles);

@example
x = 1:10;
y = ones (size (x))*2.*x;
h = stem (x, y, "-.k.");
@end example
@noindent
plots 10 stems with heights from 2 to 20
(the color is black, line style is @code{"-."} and the marker style
is @code{"."}, and @var{h} is a 2-by-10 array of handles in which the
first row holds the line handles and the second row holds the marker
handles);

@example
x = 1:10;
y = ones (size (x))*2.*x;
h = stem (x, y, "fill");
@end example
@noindent
plots 10 stems with heights from 2 to 20
(the color is rgb-triple defined, the line style is @code{"-"},
the marker style is @code{"o"}, and @var{h} is a 2-by-10 array of
handles in which the first row holds the line handles and the second
row holds the marker handles).

Color definitions with rgb-triples are not valid!

@seealso{bar, barh, plot}
@end deftypefn


@anchor{doc-stairs}
@deftypefn {Function File} {} stairs (@var{x}, @var{y})
Given two vectors of x-y data, bar produces a `stairstep' plot.

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
[xs, ys] = stairs (x, y);
plot (xs, ys);
@end example

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


@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 (See __pltopt__). 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

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

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

Two 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
errorbar(@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, "~>")
@end example

xyerrorbar plot of @var{y} versus @var{x} where @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{semilogx, semilogy, loglog, polar, mesh, contour, __pltopt__,
bar, stairs, xlabel, ylabel, title}
@end deftypefn


@anchor{doc-loglogerr}
@deftypefn {Function File} {} loglogerr (@var{args})
This function produces 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{errorbar, semilogxerr, semilogyerr, polar, mesh, contour, 
__pltopt__, bar, stairs, xlabel, ylabel, title}
@end deftypefn


@anchor{doc-semilogxerr}
@deftypefn {Function File} {} semilogxerr (@var{args})
This function produces 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{errorbar, loglogerr semilogyerr, polar, mesh, contour, __pltopt__, 
bar, stairs, xlabel, ylabel, title}
@end deftypefn


@anchor{doc-semilogyerr}
@deftypefn {Function File} {} semilogyerr (@var{args})
This function produces 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{errorbar, loglogerr semilogxerr, polar, mesh, contour, __pltopt__, 
bar, stairs,  xlabel, ylabel, title}
@end deftypefn


@node Three-Dimensional Plotting
@section Three-Dimensional Plotting

@anchor{doc-plot3}
@deftypefn {Function File} {} plot3 (@var{args})

This function produces 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
where 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 seperate
line. No attempt is made to transpose the arguments to make the
number of rows match.

Additionally, only two arguments can be given as

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

where 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

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.

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

See @code{__pltopt__} for a description of the optional format
argument.

Arguments can 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
where each set of three arguments is treated as a seperate 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 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{plot, semilogx, semilogy, loglog, polar, mesh, contour, __pltopt__
bar, stairs, errorbar, xlabel, ylabel, title, print}
@end deftypefn


@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{meshgrid, contour}
@end deftypefn


@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{meshgrid, mesh, contour}
@end deftypefn


@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{mesh, contour}
@end deftypefn


@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, ndgrid returns n arrays of dimension n. 
The elements of the ith output argument contains the elements of the vector 
@var{x}i repeated over all dimensions different from the ith 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{meshgrid}
@end deftypefn


@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


@node Manipulating Existing Plots
@section Manipulating Existing Plots

@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 
(this is not yet implemented for automatic 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 (not implemented).
@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

@end deftypefn


@anchor{doc-gca}
@deftypefn {Function File} {} gca ()
Return the current axis handle.
@end deftypefn


@anchor{doc-gcf}
@deftypefn {Function File} {} gcf ()
Return the current figure handle.
@end deftypefn


@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


@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}
in the graphics handle @var{h}.
@end deftypefn


@anchor{doc-clf}
@deftypefn {Function File} {} clf ()
Clear the current figure.
@end deftypefn


@anchor{doc-delete}
@deftypefn {Function File} {} delete (@var{file})
@deftypefnx {Function File} {} delete (@var{h})
Delete the named file or figure handle.
@end deftypefn


@anchor{doc-close}
@deftypefn {Command} {} close
@deftypefnx {Command} {} close (@var{n})
@deftypefnx {Command} {} close all
@deftypefnx {Command} {} close all hidden
Close the plot window(s).
@end deftypefn


@anchor{doc-closereq}
@deftypefn {Function File} {} closereq ()
Close the current figure.
@end deftypefn


@anchor{doc-isfigure}
@deftypefn {Function File} {} isfigure (@var{h})
Return 1 if @var{h} is a graphics handle that contains a figure
object and 0 otherwise.
@end deftypefn


@node Plot Annotations
@section Plot Annotations

@anchor{doc-title}
@deftypefn {Function File} {} title (@var{title})
Create a title object and return a handle to it.
@end deftypefn


@anchor{doc-legend}
@deftypefn {Function File} {} legend (@var{st1}, @var{st2}, @dots{})
@deftypefnx {Function File} {} legend (@var{st1}, @var{st2}, @dots{}, @var{pos})
@deftypefnx {Function File} {} legend (@var{matstr})
@deftypefnx {Function File} {} legend (@var{matstr}, @var{pos})
@deftypefnx {Function File} {} legend (@var{cell})
@deftypefnx {Function File} {} legend (@var{cell}, @var{pos})
@deftypefnx {Function File} {} legend ('@var{func}')

Legend puts a legend on the current plot using the specified strings
as labels. Use independant strings (@var{st1}, @var{st2}, @dots{}), a
matrix of strings (@var{matstr}), or a cell array of strings (@var{cell}) to
specify legends. Legend works on line graphs, bar graphs, etc.
Be sure to call plot before calling legend.

@var{pos} optionally  places the legend in the specified location:

@multitable @columnfractions 0.1 0.1 0.8
@item @tab -1 @tab
  To the top right of the plot
@item @tab 0 @tab
  Don't move the legend box (default)
@item @tab 1 @tab
  Upper right-hand corner
@item @tab 2 @tab
  Upper left-hand corner
@item @tab 3 @tab
  Lower left-hand corner
@item @tab 4 @tab
  Lower right-hand corner
@end multitable

Some specific functions are directely avaliable using @var{func}:

@table @code
@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


@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})
Create a text object with text @var{label} at position @var{x},
@var{y}, @var{z} on the current axes.  The label may be followed by
property-value pairs.
@end deftypefn


@anchor{doc-xlabel}
@deftypefn {Function File} {} xlabel (@var{string})
@deftypefnx {Function File} {} ylabel (@var{string})
@deftypefnx {Function File} {} zlabel (@var{string})
Specify x, y, and z axis labels for the plot.
@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, stairs,  ylabel, title}
@end deftypefn


@anchor{doc-box}
@deftypefn {Function File} {} box (@var{arg})
@deftypefnx {Function File} {} grid (@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{grid}
@end deftypefn


@anchor{doc-grid}
@deftypefn {Function File} {} grid (@var{arg})
@deftypefnx {Function File} {} grid ("minor", @var{arg2})
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.
@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, stairs, xlabel, ylabel, title}
@end deftypefn


@node Multiple Plots on One Page
@section Multiple Plots on One Page

@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:
@iftex
@tex
\vskip 10pt
\hfil\vbox{\offinterlineskip\hrule
\halign{\vrule#&&\qquad\hfil#\hfil\qquad\vrule\cr
height13pt&1&2&3&4\cr height12pt&&&&\cr\noalign{\hrule}
height13pt&5&6&7&8\cr height12pt&&&&\cr\noalign{\hrule}}}
\hfil
\vskip 10pt
@end tex
@end iftex
@ifinfo
@display
@group
@example

+-----+-----+-----+-----+
|  1  |  2  |  3  |  4  |
+-----+-----+-----+-----+
|  5  |  6  |  7  |  8  |
+-----+-----+-----+-----+
@end example
@end group
@end display
@end ifinfo
@seealso{plot}
@end deftypefn


@node Multiple Plot Windows
@section Multiple Plot Windows

@anchor{doc-figure}
@deftypefn {Function File} {} figure (@var{n}, @var{p}, @var{v}, @dots{})
Set the current plot window to plot window @var{n}.  If no arguments are
specified, the next available window number is chosen.  Parameters @var{p}
and settings @var{v} can be given in pairs if @var{n} is specified. 
@end deftypefn


@node Printing Plots
@section Printing Plots

@anchor{doc-print}
@deftypefn {Function File} {} print (@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, output is sent to the printer.

@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 -color
@itemx -mono
  Monochrome or colour lines.
@item -solid
@itemx -dashed
  Solid or dashed lines.
@item -portrait
@itemx -landscape
  Plot orientation, as returned by "orient".
@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 hpgl
    HP plotter language
@item fig
    XFig
@item dxf
    AutoCAD
@item mf
    Metafont
@item png
    Portable network graphics
@item pbm
    PBMplus
@item emf
    Microsoft Enhanced Metafile
@end table

  Other devices are supported by "convert" from ImageMagick.  Type
  system("convert") to see what formats are available.

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


@anchor{doc-orient}
@deftypefn {Function File} {} orient (@var{orientation})
Set default print orientation.  Valid values for @var{orientation}
include @code{"landscape"} and @code{"portrait"}.  If called with no
arguments, return the default print orientation.
@end deftypefn


@node Test Plotting Functions
@section Test Plotting Functions

@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

@iftex
@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
@end iftex
@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 funxtion 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{mesh}
@end deftypefn


@node Interaction with gnuplot
@section Interaction with @code{gnuplot}

@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


@anchor{doc-gnuplot_use_title_option}
@deftypefn {Loadable Function} {@var{val} =} gnuplot_use_title_option ()
@deftypefnx {Loadable Function} {@var{old_val} =} gnuplot_use_title_option (@var{new_val})
If enabled, append @samp{-title "Figure NN"} to the gnuplot command.
By default, this feature is enabled if the @code{DISPLAY} environment
variable is set when Octave starts.
@end deftypefn

