File: plot.texi

package info (click to toggle)
octave 3.8.2-4
links: PTS, VCS
area: main
in suites: jessie, jessie-kfreebsd
size: 84,396 kB
ctags: 45,547
sloc: cpp: 293,356; ansic: 42,041; fortran: 23,669; sh: 13,629; objc: 7,890; yacc: 7,093; lex: 3,442; java: 2,125; makefile: 1,589; perl: 1,009; awk: 974; xml: 34
file content (8983 lines) | stat: -rw-r--r-- 301,579 bytes
parent folder | download | duplicates (3)
@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

@c Copyright (C) 1996-2013 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
* Introduction to Plotting::
* High-Level Plotting::
* Graphics Data Structures::
* Advanced Plotting::
@end menu

@node Introduction to Plotting
@section Introduction to Plotting

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

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

@node High-Level Plotting
@section High-Level Plotting
@cindex plotting, high-level

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

If you need more detailed control, see @ref{Graphics Data Structures}
and @ref{Advanced Plotting}.

@menu
* Two-Dimensional Plots::
* Three-Dimensional Plots::
* Plot Annotations::
* Multiple Plots on One Page::
* Multiple Plot Windows::
* Manipulation of Plot Windows::
* Use of the @code{interpreter} Property::
* Printing and Saving Plots::
* Interacting with Plots::
* Test Plotting Functions::
@end menu

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

@menu
* Axis Configuration::
* Two-dimensional Function Plotting::
* Two-dimensional Geometric Shapes::
@end menu

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 scripts/plot/draw/plot.m
@anchor{XREFplot}
@deftypefn  {Function File} {} plot (@var{y})
@deftypefnx {Function File} {} plot (@var{x}, @var{y})
@deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} plot (@dots{}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} plot (@var{x1}, @var{y1}, @dots{}, @var{xn}, @var{yn})
@deftypefnx {Function File} {} plot (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} plot (@dots{})
Produce 2-D 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 range @code{1:numel (@var{y})}.

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 @var{x} and @var{y} are scalars, a single point is plotted.

@item
@code{squeeze()} is applied to arguments with more than two dimensions,
but no more than two singleton dimensions.

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

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

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

The @var{fmt} format argument can also be used to control the plot style.
The format is composed of three parts: linestyle, markerstyle, color. 
When a markerstyle is specified, but no linestyle, only the markers are
plotted.  Similarly, if a linestyle is specified, but no markerstyle, then
only lines are drawn.  If both are specified then lines and markers will
be plotted.  If no @var{fmt} and no @var{property}/@var{value} pairs are
given, then the default plot style is solid lines with no markers and the
color determined by the @qcode{"colororder"} property of the current axes.

Format arguments:

@table @asis
@item linestyle

@multitable @columnfractions 0.06 0.94
@item @samp{-}  @tab Use solid lines (default).
@item @samp{--} @tab Use dashed lines.
@item @samp{:}  @tab Use dotted lines.
@item @samp{-.} @tab Use dash-dotted lines.
@end multitable

@item markerstyle

@multitable @columnfractions 0.06 0.94
@item @samp{+} @tab crosshair
@item @samp{o} @tab circle
@item @samp{*} @tab star
@item @samp{.} @tab point
@item @samp{x} @tab cross
@item @samp{s} @tab square
@item @samp{d} @tab diamond
@item @samp{^} @tab upward-facing triangle
@item @samp{v} @tab downward-facing triangle
@item @samp{>} @tab right-facing triangle
@item @samp{<} @tab left-facing triangle
@item @samp{p} @tab pentagram
@item @samp{h} @tab hexagram
@end multitable

@item color

@multitable @columnfractions 0.06 0.94
@item @samp{k} @tab blacK
@item @samp{r} @tab Red
@item @samp{g} @tab Green
@item @samp{b} @tab Blue
@item @samp{m} @tab Magenta
@item @samp{c} @tab Cyan
@item @samp{w} @tab White
@end multitable

@item @qcode{";key;"}
Here @qcode{"key"} is the label to use for the plot legend.
@end table

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

Here are some plot examples:

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

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

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

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

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

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the created line objects.

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

@seealso{@ref{XREFaxis,,axis}, @ref{XREFbox,,box}, @ref{XREFgrid,,grid}, @ref{XREFhold,,hold}, @ref{XREFlegend,,legend}, @ref{XREFtitle,,title}, @ref{XREFxlabel,,xlabel}, @ref{XREFylabel,,ylabel}, @ref{XREFxlim,,xlim}, @ref{XREFylim,,ylim}, @ref{XREFezplot,,ezplot}, @ref{XREFerrorbar,,errorbar}, @ref{XREFfplot,,fplot}, @ref{XREFline,,line}, @ref{XREFplot3,,plot3}, @ref{XREFpolar,,polar}, @ref{XREFloglog,,loglog}, @ref{XREFsemilogx,,semilogx}, @ref{XREFsemilogy,,semilogy}, @ref{XREFsubplot,,subplot}}
@end deftypefn


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

@c plotyy scripts/plot/draw/plotyy.m
@anchor{XREFplotyy}
@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{hax}, @dots{})
@deftypefnx {Function File} {[@var{ax}, @var{h1}, @var{h2}] =} plotyy (@dots{})
Plot 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 the first argument @var{hax} is an axes handle, then it defines
the principal axis in which to plot the @var{x1} and @var{y1} data.

The return value @var{ax} is a vector with the axis handles of the two
y axes.  @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
@seealso{@ref{XREFplot,,plot}}
@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 semilogx scripts/plot/draw/semilogx.m
@anchor{XREFsemilogx}
@deftypefn  {Function File} {} semilogx (@var{y})
@deftypefnx {Function File} {} semilogx (@var{x}, @var{y})
@deftypefnx {Function File} {} semilogx (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} semilogx (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} semilogx (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} semilogx (@dots{})
Produce a 2-D plot using a logarithmic scale for the x-axis.

See the documentation of @code{plot} for a description of the
arguments that @code{semilogx} will accept.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.
@seealso{@ref{XREFplot,,plot}, @ref{XREFsemilogy,,semilogy}, @ref{XREFloglog,,loglog}}
@end deftypefn


@c semilogy scripts/plot/draw/semilogy.m
@anchor{XREFsemilogy}
@deftypefn  {Function File} {} semilogy (@var{y})
@deftypefnx {Function File} {} semilogy (@var{x}, @var{y})
@deftypefnx {Function File} {} semilogy (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} semilogy (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} semilogy (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} semilogy (@dots{})
Produce a 2-D plot using a logarithmic scale for the y-axis.

See the documentation of @code{plot} for a description of the
arguments that @code{semilogy} will accept.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.
@seealso{@ref{XREFplot,,plot}, @ref{XREFsemilogx,,semilogx}, @ref{XREFloglog,,loglog}}
@end deftypefn


@c loglog scripts/plot/draw/loglog.m
@anchor{XREFloglog}
@deftypefn  {Function File} {} loglog (@var{y})
@deftypefnx {Function File} {} loglog (@var{x}, @var{y})
@deftypefnx {Function File} {} loglog (@var{x}, @var{y}, @var{prop}, @var{value}, @dots{})
@deftypefnx {Function File} {} loglog (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} loglog (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} loglog (@dots{})
Produce a 2-D plot using logarithmic scales for both axes.

See the documentation of @code{plot} for a description of the arguments
that @code{loglog} will accept.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.
@seealso{@ref{XREFplot,,plot}, @ref{XREFsemilogx,,semilogx}, @ref{XREFsemilogy,,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 bar scripts/plot/draw/bar.m
@anchor{XREFbar}
@deftypefn  {Function File} {} bar (@var{y})
@deftypefnx {Function File} {} bar (@var{x}, @var{y})
@deftypefnx {Function File} {} bar (@dots{}, @var{w})
@deftypefnx {Function File} {} bar (@dots{}, @var{style})
@deftypefnx {Function File} {} bar (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} bar (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} bar (@dots{}, @var{prop}, @var{val}, @dots{})
Produce a bar graph from two vectors of X-Y data.

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

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

If @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 following values:

@table @asis
@item @qcode{"grouped"} (default) 
Side-by-side bars with a gap between bars and centered over the X-coordinate.

@item  @qcode{"stacked"}
Bars are stacked so that each X value has a single bar composed of
multiple segments.

@item @qcode{"hist"}
Side-by-side bars with no gap between bars and centered over the
X-coordinate.

@item @qcode{"histc"}
Side-by-side bars with no gap between bars and left-aligned to the
X-coordinate.
@end table

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of handles to the created
"bar series" hggroups with one handle per column of the variable @var{y}.
This series makes it possible to change a common element in one bar series
object and have the change reflected in the other "bar series".
For example,

@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 following example modifies the face and edge colors using
property/value pairs.

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

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

@example
@group
bar (rand (10, 3));
colormap (summer (64));
@end group
@end example

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

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

@seealso{@ref{XREFbarh,,barh}, @ref{XREFhist,,hist}, @ref{XREFpie,,pie}, @ref{XREFplot,,plot}, @ref{XREFpatch,,patch}}
@end deftypefn


@c barh scripts/plot/draw/barh.m
@anchor{XREFbarh}
@deftypefn  {Function File} {} barh (@var{y})
@deftypefnx {Function File} {} barh (@var{x}, @var{y})
@deftypefnx {Function File} {} barh (@dots{}, @var{w})
@deftypefnx {Function File} {} barh (@dots{}, @var{style})
@deftypefnx {Function File} {} barh (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} barh (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} barh (@dots{}, @var{prop}, @var{val}, @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 the range @code{1:numel (@var{y})}.

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

If @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 following values:

@table @asis
@item @qcode{"grouped"} (default) 
Side-by-side bars with a gap between bars and centered over the Y-coordinate.

@item  @qcode{"stacked"}
Bars are stacked so that each Y value has a single bar composed of
multiple segments.

@item @qcode{"hist"}
Side-by-side bars with no gap between bars and centered over the
Y-coordinate.

@item @qcode{"histc"}
Side-by-side bars with no gap between bars and left-aligned to the
Y-coordinate.
@end table

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
bar series hggroup.  For a description of the use of the
bar series, @pxref{XREFbar,,bar}.
@seealso{@ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFpie,,pie}, @ref{XREFplot,,plot}, @ref{XREFpatch,,patch}}
@end deftypefn


@c hist scripts/plot/draw/hist.m
@anchor{XREFhist}
@deftypefn  {Function File} {} hist (@var{y})
@deftypefnx {Function File} {} hist (@var{y}, @var{x})
@deftypefnx {Function File} {} hist (@var{y}, @var{nbins})
@deftypefnx {Function File} {} hist (@var{y}, @var{x}, @var{norm})
@deftypefnx {Function File} {} hist (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} hist (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{nn}, @var{xx}] =} hist (@dots{})
Produce histogram counts or plots.

With one vector input argument, @var{y}, 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, @var{y}, plot a
histogram where each bin contains a bar per input column.

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

If scalar, the second argument, @var{nbins}, defines the number of bins.

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

Extreme values are lumped into the first and last bins.

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

@example
@group
hist (randn (1, 100), 25, "facecolor", "r", "edgecolor", "b");
@end group
@end example

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

@example
@group
hist (rand (10, 3));
colormap (summer ());
@end group
@end example

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

With two output arguments, produce the values @var{nn} (numbers of elements)
and @var{xx} (bin centers) such that @code{bar (@var{xx}, @var{nn})} will
plot the histogram.

@seealso{@ref{XREFhistc,,histc}, @ref{XREFbar,,bar}, @ref{XREFpie,,pie}, @ref{XREFrose,,rose}}
@end deftypefn


@c stemleaf scripts/plot/draw/stemleaf.m
@anchor{XREFstemleaf}
@deftypefn  {Function File} {} stemleaf (@var{x}, @var{caption})
@deftypefnx {Function File} {} stemleaf (@var{x}, @var{caption}, @var{stem_sz})
@deftypefnx {Function File} {@var{plotstr} =} stemleaf (@dots{})
Compute and display a stem and leaf plot of the vector @var{x}.

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

The optional input @var{stem_sz} sets the width of each stem.
The stem width is determined by @code{10^(@var{stem_sz} + 1)}.
The default stem width is 10.

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

@example
@group

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

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

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

The leaf digits are not sorted.  If sorted leaf values are desired, use
@code{@var{xs} = sort (@var{x})} before calling @code{stemleaf (@var{xs})}.

The stem and leaf plot and associated displays are described in: 
Ch. 3, @cite{Exploratory Data Analysis} by J. W. Tukey, Addison-Wesley, 1977.
@seealso{@ref{XREFhist,,hist}, @ref{XREFprintd,,printd}}
@end deftypefn


@c printd scripts/plot/util/printd.m
@anchor{XREFprintd}
@deftypefn  {Function File} {} printd (@var{obj}, @var{filename})
@deftypefnx {Function File} {@var{out_file} =} printd (@dots{})

Convert any object acceptable to @code{disp} into the format
selected by the suffix of @var{filename}.  If the return argument
@var{out_file} is given, the name of the created file is returned.

This function is intended to facilitate manipulation of the output
of functions such as @code{stemleaf}.
@seealso{@ref{XREFstemleaf,,stemleaf}}
@end deftypefn


@c stairs scripts/plot/draw/stairs.m
@anchor{XREFstairs}
@deftypefn  {Function File} {} stairs (@var{y})
@deftypefnx {Function File} {} stairs (@var{x}, @var{y})
@deftypefnx {Function File} {} stairs (@dots{}, @var{style})
@deftypefnx {Function File} {} stairs (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} stairs (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} stairs (@dots{})
@deftypefnx {Function File} {[@var{xstep}, @var{ystep}] =} stairs (@dots{})
Produce a stairstep plot.

The arguments @var{x} and @var{y} may be vectors or matrices.
If only one argument is given, it is taken as a vector of Y values
and the X coordinates are taken to be the indices of the elements.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.

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

If the first argument @var{hax} is an axis handle, then plot into this axis,
rather than the current axis handle returned by @code{gca}.

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

@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{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFplot,,plot}, @ref{XREFstem,,stem}}
@end deftypefn


@c stem scripts/plot/draw/stem.m
@anchor{XREFstem}
@deftypefn  {Function File} {} stem (@var{y})
@deftypefnx {Function File} {} stem (@var{x}, @var{y})
@deftypefnx {Function File} {} stem (@dots{}, @var{linespec})
@deftypefnx {Function File} {} stem (@dots{}, "filled")
@deftypefnx {Function File} {} stem (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} stem (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} stem (@dots{})
Plot a 2-D stem graph.

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

If @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 @qcode{"b"} (blue), the default line style is
@qcode{"-"}, and the default marker is @qcode{"o"}.  The line style can
be altered by the @code{linespec} argument in the same manner as the
@code{plot} command.  If the @qcode{"filled"} argument is present the
markers at the top of the stems will be filled in.  For example,

@example
@group
x = 1:10;
y = 2*x;
stem (x, y, "r");
@end group
@end example

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

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a handle to a @nospell{"stem series"}
hggroup.  The single hggroup handle has all of the graphical elements
comprising the plot as its children; This allows the properties of
multiple graphics objects to be changed by modifying just a single
property of the @nospell{"stem series"} hggroup.

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 @nospell{"stem series"} and moves the base
line of the first.

Stem Series Properties

@table @asis
@item linestyle
The linestyle of the stem.  (Default: @qcode{"-"})

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

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

@item marker
The marker symbol to use at the top of each stem.  (Default: @qcode{"o"})

@item markeredgecolor
The edge color of the marker.  (Default: @qcode{"color"} property)

@item markerfacecolor
The color to use for @nospell{"filling"} the marker.  
(Default: @qcode{"none"} [unfilled])

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

@item baseline
The handle of the line object which implements the baseline.  Use @code{set}
with the returned handle to change graphic properties of the baseline.

@item basevalue
The y-value where the baseline is drawn.  (Default: 0)
@end table
@seealso{@ref{XREFstem3,,stem3}, @ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFplot,,plot}, @ref{XREFstairs,,stairs}}
@end deftypefn


@c stem3 scripts/plot/draw/stem3.m
@anchor{XREFstem3}
@deftypefn  {Function File} {} stem3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} stem3 (@dots{}, @var{linespec})
@deftypefnx {Function File} {} stem3 (@dots{}, "filled")
@deftypefnx {Function File} {} stem3 (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} stem3 (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} stem3 (@dots{})
Plot a 3-D stem graph.

Stems are drawn from the height @var{z} to the location in the x-y plane
determined by @var{x} and @var{y}.  The default color is @qcode{"b"} (blue),
the default line style is @qcode{"-"}, and the default marker is @qcode{"o"}.

The line style can be altered by the @code{linespec} argument in the same
manner as the @code{plot} command.  If the @qcode{"filled"} argument is
present the markers at the top of the stems will be filled in.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a handle to the @nospell{"stem series"}
hggroup containing the line and marker objects used for the plot.
@xref{XREFstem,,stem}, for a description of the @nospell{"stem series"}
object.

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.

Implementation Note: Color definitions with RGB-triples are not valid.
@seealso{@ref{XREFstem,,stem}, @ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFplot,,plot}}
@end deftypefn


@c scatter scripts/plot/draw/scatter.m
@anchor{XREFscatter}
@deftypefn  {Function File} {} scatter (@var{x}, @var{y})
@deftypefnx {Function File} {} scatter (@var{x}, @var{y}, @var{s})
@deftypefnx {Function File} {} scatter (@var{x}, @var{y}, @var{s}, @var{c})
@deftypefnx {Function File} {} scatter (@dots{}, @var{style})
@deftypefnx {Function File} {} scatter (@dots{}, "filled")
@deftypefnx {Function File} {} scatter (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} scatter (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} scatter (@dots{})
Draw a 2-D scatter plot.

A marker is plotted at each point defined by the coordinates in the vectors
@var{x} and @var{y}.

The size of the markers is determined by @var{s}, which can be a scalar
or a vector of the same length as @var{x} and @var{y}.  If @var{s}
is not given, or is an empty matrix, then a default value of 8 points is
used.

The color of the markers is determined by @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 an @nospell{Nx3} matrix defining
the RGB color of each marker 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 no marker is specified it defaults to @qcode{"o"} or circles.
If the argument @qcode{"filled"} is given then the markers are filled.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

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

Example:

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

@seealso{@ref{XREFscatter3,,scatter3}, @ref{XREFpatch,,patch}, @ref{XREFplot,,plot}}
@end deftypefn


@c plotmatrix scripts/plot/draw/plotmatrix.m
@anchor{XREFplotmatrix}
@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{hax}, @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} 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 the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

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:

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

@seealso{@ref{XREFscatter,,scatter}, @ref{XREFplot,,plot}}
@end deftypefn


@c pareto scripts/plot/draw/pareto.m
@anchor{XREFpareto}
@deftypefn  {Function File} {} pareto (@var{y})
@deftypefnx {Function File} {} pareto (@var{y}, @var{x})
@deftypefnx {Function File} {} pareto (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} pareto (@dots{})
Draw a Pareto chart.

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

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

Typically only the magnitude data @var{y} is present in which case
@var{x} is taken to be the range @code{1 : length (@var{y})}.  If @var{x}
is given it may be a string array, a cell array of strings, or a numerical
vector.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle for the created bar plot and a second handle for the created line
plot.

An example of the use of @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
@seealso{@ref{XREFbar,,bar}, @ref{XREFbarh,,barh}, @ref{XREFhist,,hist}, @ref{XREFpie,,pie}, @ref{XREFplot,,plot}}
@end deftypefn


@c rose scripts/plot/draw/rose.m
@anchor{XREFrose}
@deftypefn  {Function File} {} rose (@var{th})
@deftypefnx {Function File} {} rose (@var{th}, @var{nbins})
@deftypefnx {Function File} {} rose (@var{th}, @var{bins})
@deftypefnx {Function File} {} rose (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} rose (@dots{})
@deftypefnx {Function File} {[@var{thout} @var{rout}] =} rose (@dots{})
Plot an angular histogram.

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

If @var{nbins} is given and is a scalar, then the histogram is produced with
@var{nbin} bins.  If @var{bins} is a vector, then the center of each bin is
defined by the values of @var{bins} and the number of bins is
given by the number of elements in @var{bins}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to the
line objects representing each histogram.

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

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

@seealso{@ref{XREFhist,,hist}, @ref{XREFpolar,,polar}}
@end deftypefn


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

@c contour scripts/plot/draw/contour.m
@anchor{XREFcontour}
@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{hax}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contour (@dots{})
Create a 2-D contour plot.

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 appearance of contour lines can be defined with a line style @var{style}
in the same manner as @code{plot}.  Only line style and color are used;
Any markers defined by @var{style} are ignored.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional output @var{c} are the contour levels in @code{contourc} format.

The optional return value @var{h} is a graphics handle to the hggroup
comprising the contour lines.

Example:

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

@seealso{@ref{XREFezcontour,,ezcontour}, @ref{XREFcontourc,,contourc}, @ref{XREFcontourf,,contourf}, @ref{XREFcontour3,,contour3}, @ref{XREFclabel,,clabel}, @ref{XREFmeshc,,meshc}, @ref{XREFsurfc,,surfc}, @ref{XREFcaxis,,caxis}, @ref{XREFcolormap,,colormap}, @ref{XREFplot,,plot}}

@end deftypefn


@c contourf scripts/plot/draw/contourf.m
@anchor{XREFcontourf}
@deftypefn  {Function File} {} contourf (@var{z})
@deftypefnx {Function File} {} contourf (@var{z}, @var{vn})
@deftypefnx {Function File} {} contourf (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} contourf (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {Function File} {} contourf (@dots{}, @var{style})
@deftypefnx {Function File} {} contourf (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@dots{})
Create a 2-D contour plot with filled intervals.

Plot level curves (contour lines) of the matrix @var{z} and fill the region
between lines with colors from the current colormap.

The level curves are taken from the contour matrix @var{c} computed by
@code{contourc} for the same arguments; see the latter for their
interpretation.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional output @var{c} are the contour levels in @code{contourc} format.

The optional return value @var{h} is a graphics handle to the hggroup
comprising the contour lines.

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{XREFezcontourf,,ezcontourf}, @ref{XREFcontour,,contour}, @ref{XREFcontourc,,contourc}, @ref{XREFcontour3,,contour3}, @ref{XREFclabel,,clabel}, @ref{XREFmeshc,,meshc}, @ref{XREFsurfc,,surfc}, @ref{XREFcaxis,,caxis}, @ref{XREFcolormap,,colormap}, @ref{XREFplot,,plot}}
@end deftypefn


@c contourc scripts/plot/draw/contourc.m
@anchor{XREFcontourc}
@deftypefn  {Function File} {[@var{c}, @var{lev}] =} contourc (@var{z})
@deftypefnx {Function File} {[@var{c}, @var{lev}] =} contourc (@var{z}, @var{vn})
@deftypefnx {Function File} {[@var{c}, @var{lev}] =} contourc (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {[@var{c}, @var{lev}] =} contourc (@var{x}, @var{y}, @var{z}, @var{vn})
Compute contour lines (isolines of constant Z value).

The matrix @var{z} contains height values above the rectangular grid
determined by @var{x} and @var{y}.  If only a single input @var{z} is
provided then @var{x} is taken to be @code{1:rows (@var{z})} and @var{y} is
taken to be @code{1:columns (@var{z})}.

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

The return value @var{c} is a 2x@var{n} matrix containing the
contour lines in the following format

@example
@group
@var{c} = [lev1, x1, x2, @dots{}, levn, x1, x2, ...
     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}.

The optional return value @var{lev} is a vector with the Z values of
of the contour levels.

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{XREFcontour,,contour}, @ref{XREFcontourf,,contourf}, @ref{XREFcontour3,,contour3}, @ref{XREFclabel,,clabel}}
@end deftypefn


@c contour3 scripts/plot/draw/contour3.m
@anchor{XREFcontour3}
@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{hax}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contour3 (@dots{})
Create a 3-D contour plot.

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

The level curves are taken from the contour matrix @var{c} computed by
@code{contourc} for the same arguments; see the latter for their
interpretation.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional output @var{c} are the contour levels in @code{contourc} format.

The optional return value @var{h} is a graphics handle to the hggroup
comprising the contour lines.

Example:

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

@seealso{@ref{XREFcontour,,contour}, @ref{XREFcontourc,,contourc}, @ref{XREFcontourf,,contourf}, @ref{XREFclabel,,clabel}, @ref{XREFmeshc,,meshc}, @ref{XREFsurfc,,surfc}, @ref{XREFcaxis,,caxis}, @ref{XREFcolormap,,colormap}, @ref{XREFplot,,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 errorbar scripts/plot/draw/errorbar.m
@anchor{XREFerrorbar}
@deftypefn  {Function File} {} errorbar (@var{y}, @var{ey})
@deftypefnx {Function File} {} errorbar (@var{y}, @dots{}, @var{fmt})
@deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{ey})
@deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {Function File} {} errorbar (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {Function File} {} errorbar (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} errorbar (@dots{})
Create a 2-D plot 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, the
second argument @var{ey} are the errors around the @var{y} values, and the
@var{x} coordinates are taken to be the indices of the elements
(@code{1:numel (@var{y})}).

The general form of the function is

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

@noindent
After the @var{x} and @var{y} arguments there can be 1, 2, or 4
parameters specifying the error values depending on the nature of the error
values and the plot format @var{fmt}.

@table @asis
@item @var{err} (scalar)
When the error is a scalar all points share the same error value.
The errorbars are symmetric and are drawn from @var{data}-@var{err} to
@var{data}+@var{err}.
The @var{fmt} argument determines whether @var{err} is in the x-direction, 
y-direction (default), or both.

@item @var{err} (vector or matrix)
Each data point has a particular error value.
The errorbars are symmetric and are drawn from @var{data}(n)-@var{err}(n) to
@var{data}(n)+@var{err}(n).

@item @var{lerr}, @var{uerr} (scalar)
The errors have a single low-side value and a single upper-side value.
The errorbars are not symmetric and are drawn from @var{data}-@var{lerr} to
@var{data}+@var{uerr}.

@item @var{lerr}, @var{uerr} (vector or matrix)
Each data point has a low-side error and an upper-side error.
The errorbars are not symmetric and are drawn from
@var{data}(n)-@var{lerr}(n) to @var{data}(n)+@var{uerr}(n).
@end table

Any number of data sets (@var{x1},@var{y1}, @var{x2},@var{y2}, @dots{}) may
appear as long as they are separated by a format string @var{fmt}.

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

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

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

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

@item >
Set xerrorbars plot style.

@item ~>
Set xyerrorbars plot style.

@item #~
Set yboxes plot style.

@item #
Set xboxes plot style.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a handle to the hggroup object
representing the data plot and errorbars.

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

Examples:

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

@noindent
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}.  The marker
@qcode{"."} is used so no connecting line is drawn and the errorbars
appear in red.

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

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

@noindent
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{XREFsemilogxerr,,semilogxerr}, @ref{XREFsemilogyerr,,semilogyerr}, @ref{XREFloglogerr,,loglogerr}, @ref{XREFplot,,plot}}
@end deftypefn


@c semilogxerr scripts/plot/draw/semilogxerr.m
@anchor{XREFsemilogxerr}
@deftypefn  {Function File} {} semilogxerr (@var{y}, @var{ey})
@deftypefnx {Function File} {} semilogxerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {Function File} {} semilogxerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {Function File} {} semilogxerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {Function File} {} semilogxerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {Function File} {} semilogxerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {Function File} {} semilogxerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {Function File} {} semilogxerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {Function File} {} semilogxerr (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} semilogxerr (@dots{})
Produce 2-D plots using a logarithmic scale for the x-axis and
errorbars at each data point.

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

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

@noindent
which produces a semi-logarithmic 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}.  @xref{XREFerrorbar,,errorbar}, for available
formats and additional information.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

@seealso{@ref{XREFerrorbar,,errorbar}, @ref{XREFsemilogyerr,,semilogyerr}, @ref{XREFloglogerr,,loglogerr}}
@end deftypefn


@c semilogyerr scripts/plot/draw/semilogyerr.m
@anchor{XREFsemilogyerr}
@deftypefn  {Function File} {} semilogyerr (@var{y}, @var{ey})
@deftypefnx {Function File} {} semilogyerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {Function File} {} semilogyerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {Function File} {} semilogyerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {Function File} {} semilogyerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {Function File} {} semilogyerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {Function File} {} semilogyerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {Function File} {} semilogyerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {Function File} {} semilogyerr (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} semilogyerr (@dots{})
Produce 2-D plots using a logarithmic scale for the y-axis and
errorbars at each data point.

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

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

@noindent
which produces a semi-logarithmic 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}.  @xref{XREFerrorbar,,errorbar}, for available
formats and additional information.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

@seealso{@ref{XREFerrorbar,,errorbar}, @ref{XREFsemilogxerr,,semilogxerr}, @ref{XREFloglogerr,,loglogerr}}
@end deftypefn


@c loglogerr scripts/plot/draw/loglogerr.m
@anchor{XREFloglogerr}
@deftypefn  {Function File} {} loglogerr (@var{y}, @var{ey})
@deftypefnx {Function File} {} loglogerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {Function File} {} loglogerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {Function File} {} loglogerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {Function File} {} loglogerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {Function File} {} loglogerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {Function File} {} loglogerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {Function File} {} loglogerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {Function File} {} loglogerr (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} loglogerr (@dots{})
Produce 2-D plots on a double logarithm axis with errorbars.

Many different combinations of arguments are possible.  The most common
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}.  @xref{XREFerrorbar,,errorbar}, for available
formats and additional information.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.
@seealso{@ref{XREFerrorbar,,errorbar}, @ref{XREFsemilogxerr,,semilogxerr}, @ref{XREFsemilogyerr,,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 polar scripts/plot/draw/polar.m
@anchor{XREFpolar}
@deftypefn  {Function File} {} polar (@var{theta}, @var{rho})
@deftypefnx {Function File} {} polar (@var{theta}, @var{rho}, @var{fmt})
@deftypefnx {Function File} {} polar (@var{cplx})
@deftypefnx {Function File} {} polar (@var{cplx}, @var{fmt})
@deftypefnx {Function File} {} polar (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} polar (@dots{})
Create a 2-D plot from polar coordinates @var{theta} and @var{rho}.

If a single complex input @var{cplx} is given then the real part is used
for @var{theta} and the imaginary part is used for @var{rho}.

The optional argument @var{fmt} specifies the line format in the same way
as @code{plot}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

@seealso{@ref{XREFrose,,rose}, @ref{XREFcompass,,compass}, @ref{XREFplot,,plot}}
@end deftypefn


@c pie scripts/plot/draw/pie.m
@anchor{XREFpie}
@deftypefn  {Function File} {} pie (@var{x})
@deftypefnx {Function File} {} pie (@dots{}, @var{explode})
@deftypefnx {Function File} {} pie (@dots{}, @var{labels})
@deftypefnx {Function File} {} pie (@var{hax}, @dots{});
@deftypefnx {Function File} {@var{h} =} pie (@dots{});
Plot a 2-D pie chart.

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

The optional input @var{explode} is a vector of the same length as @var{x}
that, if non-zero, "explodes" the slice from the pie chart.

The optional input @var{labels} is a cell array of strings of the same
length as @var{x} specifying the label for each slice.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a list of handles to the patch
and text objects generating the plot.

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

@seealso{@ref{XREFpie3,,pie3}, @ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFrose,,rose}}
@end deftypefn


@c pie3 scripts/plot/draw/pie3.m
@anchor{XREFpie3}
@deftypefn  {Function File} {} pie3 (@var{x})
@deftypefnx {Function File} {} pie3 (@dots{}, @var{explode})
@deftypefnx {Function File} {} pie3 (@dots{}, @var{labels})
@deftypefnx {Function File} {} pie3 (@var{hax}, @dots{});
@deftypefnx {Function File} {@var{h} =} pie3 (@dots{});
Plot a 3-D pie chart.

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

The optional input @var{explode} is a vector of the same length as @var{x}
that, if non-zero, "explodes" the slice from the pie chart.

The optional input @var{labels} is a cell array of strings of the same
length as @var{x} specifying the label for each slice.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a list of graphics handles to the
patch, surface, and text objects generating the plot.

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

@seealso{@ref{XREFpie,,pie}, @ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFrose,,rose}}
@end deftypefn


@c quiver scripts/plot/draw/quiver.m
@anchor{XREFquiver}
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} quiver (@dots{})

Plot the (@var{u}, @var{v}) components of a vector field in
an (@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 0.9.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.
If a marker is specified then markers at the grid points of the vectors are
drawn rather than arrows.  If the argument @qcode{"filled"} is given then
the markers are filled.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to a quiver object.
A quiver object regroups the components of the quiver plot (body, arrow,
and marker), and allows them to be changed together.

Example:

@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{XREFquiver3,,quiver3}, @ref{XREFcompass,,compass}, @ref{XREFfeather,,feather}, @ref{XREFplot,,plot}}
@end deftypefn


@c quiver3 scripts/plot/draw/quiver3.m
@anchor{XREFquiver3}
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} quiver3 (@dots{})

Plot the (@var{u}, @var{v}, @var{w}) components of a vector field in
an (@var{x}, @var{y}, @var{z}) meshgrid.  If the grid is uniform, you
can specify @var{x}, @var{y}, and @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 0.9.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.
If a marker is specified then markers at the grid points of the vectors are
drawn rather than arrows.  If the argument @qcode{"filled"} is given then the
markers are filled.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to a quiver object.
A quiver object regroups the components of the quiver plot (body, arrow,
and marker), and allows them to be changed together.

@example
@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{XREFquiver,,quiver}, @ref{XREFcompass,,compass}, @ref{XREFfeather,,feather}, @ref{XREFplot,,plot}}
@end deftypefn


@c compass scripts/plot/draw/compass.m
@anchor{XREFcompass}
@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{hax}, @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.

The arrow representing each vector has one end at the origin and the tip at
[@var{u}(i), @var{v}(i)].  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}
of the same format as the @code{plot} command.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to the
line objects representing the drawn vectors.

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

@seealso{@ref{XREFpolar,,polar}, @ref{XREFfeather,,feather}, @ref{XREFquiver,,quiver}, @ref{XREFrose,,rose}, @ref{XREFplot,,plot}}
@end deftypefn


@c feather scripts/plot/draw/feather.m
@anchor{XREFfeather}
@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{hax}, @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}
of the same format as the @code{plot} command.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to the
line objects representing the drawn vectors.

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

@seealso{@ref{XREFplot,,plot}, @ref{XREFquiver,,quiver}, @ref{XREFcompass,,compass}}
@end deftypefn


@c pcolor scripts/plot/draw/pcolor.m
@anchor{XREFpcolor}
@deftypefn  {Function File} {} pcolor (@var{x}, @var{y}, @var{c})
@deftypefnx {Function File} {} pcolor (@var{c})
@deftypefnx {Function File} {} pcolor (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} pcolor (@dots{})
Produce a 2-D density plot.

A @code{pcolor} plot draws rectangles with colors from the matrix @var{c}
over the two-dimensional region represented by the matrices @var{x} and
@var{y}.  @var{x} and @var{y} are the coordinates of the mesh's vertices
and are typically the output of @code{meshgrid}.  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 values in @var{c} are scaled to span the range of the current
colormap.  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 each of 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
@qcode{"faceted"}, which renders a single color for each cell's face with
the edge visible.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@seealso{@ref{XREFcaxis,,caxis}, @ref{XREFshading,,shading}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFcontour,,contour}, @ref{XREFimagesc,,imagesc}}
@end deftypefn


@c area scripts/plot/draw/area.m
@anchor{XREFarea}
@deftypefn  {Function File} {} area (@var{y})
@deftypefnx {Function File} {} area (@var{x}, @var{y})
@deftypefnx {Function File} {} area (@dots{}, @var{lvl})
@deftypefnx {Function File} {} area (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} area (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} area (@dots{})
Area plot of the columns of @var{y}.

This plot shows the contributions of each column value to the row sum.  It
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 defaults to @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.  The default level is 0.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the hggroup
object comprising the area patch objects.  The @qcode{"BaseValue"} property
of the hggroup can be used to adjust the level where shading begins.

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

@example
@group
t = linspace (0, 2*pi, 100)';
y = [sin(t).^2, cos(t).^2)];
area (t, y);
legend ("sin^2", "cos^2", "location", "NorthEastOutside");
@end group
@end example
@seealso{@ref{XREFplot,,plot}, @ref{XREFpatch,,patch}}
@end deftypefn


@c comet scripts/plot/draw/comet.m
@anchor{XREFcomet}
@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{hax}, @dots{})
Produce a simple comet style animation along the trajectory provided by
the input coordinate vectors (@var{x}, @var{y}).  If @var{x} is not
specified it defaults to the indices of @var{y}.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.
@seealso{@ref{XREFcomet3,,comet3}}
@end deftypefn


@c comet3 scripts/plot/draw/comet3.m
@anchor{XREFcomet3}
@deftypefn  {Function File} {} comet3 (@var{z})
@deftypefnx {Function File} {} comet3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} comet3 (@var{x}, @var{y}, @var{z}, @var{p})
@deftypefnx {Function File} {} comet3 (@var{hax}, @dots{})
Produce a simple comet style animation along the trajectory provided by
the input coordinate vectors (@var{x}, @var{y}, @var{z}).  If only @var{z}
is specified then @var{x}, @var{y} default to the indices of @var{z}.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.
@seealso{@ref{XREFcomet,,comet}}
@end deftypefn


@node Axis Configuration
@subsubsection Axis Configuration

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

@c axis scripts/plot/appearance/axis.m
@anchor{XREFaxis}
@deftypefn  {Function File} {} axis ()
@deftypefnx {Function File} {} axis ([@var{x}_lo @var{x}_hi])
@deftypefnx {Function File} {} axis ([@var{x}_lo @var{x}_hi @var{y}_lo @var{y}_hi])
@deftypefnx {Function File} {} axis ([@var{x}_lo @var{x}_hi @var{y}_lo @var{y}_hi @var{z}_lo @var{z}_hi])
@deftypefnx {Function File} {} axis (@var{option})
@deftypefnx {Function File} {} axis (@dots{}, @var{option})
@deftypefnx {Function File} {} axis (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{limits} =} axis ()
Set axis limits and appearance.

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{@var{limits} = axis} returns the current
axis limits.

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

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

@noindent
forces a square aspect ratio, and

@example
axis ("tic", "labely");
@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 @asis
@item @qcode{"square"}
Force a square aspect ratio.

@item @qcode{"equal"}
Force x distance to equal y-distance.

@item @qcode{"normal"}
Restore default aspect ratio.
@end table

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

@table @asis
@item @qcode{"auto"}
Set the specified axes to have nice limits around the data
or all if no axes are specified.

@item @qcode{"manual"}
Fix the current axes limits.

@item @qcode{"tight"}
Fix axes to the limits of the data.

@item @qcode{"image"}
Equivalent to @qcode{"tight"} and @qcode{"equal"}.
@end table

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

@table @asis
@item @qcode{"on"}
Turn tic marks and labels on for all axes.

@item @qcode{"off"}
Turn tic marks off for all axes.

@item @qcode{"tic[xyz]"}
Turn tic marks on for all axes, or turn them on for the
specified axes and off for the remainder.

@item @qcode{"label[xyz]"}
Turn tic labels on for all axes, or turn them on for the
specified axes and off for the remainder.

@item @qcode{"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 @asis
@item @qcode{"ij"}
Reverse y-axis, so lower values are nearer the top.

@item @qcode{"xy"}
Restore y-axis, so higher values are nearer the top.
@end table

If the first argument @var{hax} is an axes handle, then operate on
this axes rather than the current axes returned by @code{gca}.

@seealso{@ref{XREFxlim,,xlim}, @ref{XREFylim,,ylim}, @ref{XREFzlim,,zlim}, @ref{XREFdaspect,,daspect}, @ref{XREFpbaspect,,pbaspect}, @ref{XREFbox,,box}, @ref{XREFgrid,,grid}}
@end deftypefn


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

@c caxis scripts/plot/appearance/caxis.m
@anchor{XREFcaxis}
@deftypefn  {Function File} {} caxis ([cmin cmax])
@deftypefnx {Function File} {} caxis ("auto")
@deftypefnx {Function File} {} caxis ("manual")
@deftypefnx {Function File} {} caxis (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{limits} =} caxis ()
Query or set color axis limits for plots.

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

If the @qcode{"auto"} option is given then automatic colormap limits are
applied.  The automatic algorithm sets @var{cmin} to the minimum data value
and @var{cmax} to the maximum data value.  If @qcode{"manual"} is specified
then the @qcode{"climmode"} property is set to @qcode{"manual"} and the
numeric values in the @qcode{"clim"} property are used for limits.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

Called without arguments the current color axis limits are returned.
@seealso{@ref{XREFcolormap,,colormap}}
@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.

@c Add cross-references and function index entries for other limit functions.
@anchor{XREFylim}
@anchor{XREFzlim}
@findex ylim
@findex zlim
@c xlim scripts/plot/appearance/xlim.m
@anchor{XREFxlim}
@deftypefn  {Function File} {@var{xlimits} =} xlim ()
@deftypefnx {Function File} {@var{xmode} =} xlim ("mode")
@deftypefnx {Function File} {} xlim ([@var{x_lo} @var{x_hi}])
@deftypefnx {Function File} {} xlim ("auto")
@deftypefnx {Function File} {} xlim ("manual")
@deftypefnx {Function File} {} xlim (@var{hax}, @dots{})
Query or set the limits of the x-axis for the current plot.

Called without arguments @code{xlim} returns the x-axis limits of the
current plot.  With the input query @qcode{"mode"}, return the current
x-limit calculation mode which is either @qcode{"auto"} or @qcode{"manual"}.

If passed a 2-element vector [@var{x_lo} @var{x_hi}], the limits of the
x-axis are set to these values and the mode is set to @qcode{"manual"}.

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

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.
@seealso{@ref{XREFylim,,ylim}, @ref{XREFzlim,,zlim}, @ref{XREFaxis,,axis}, @ref{XREFset,,set}, @ref{XREFget,,get}, @ref{XREFgca,,gca}}
@end deftypefn


@node Two-dimensional Function Plotting
@subsubsection Two-dimensional Function Plotting
@cindex plotting, two-dimensional functions

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 fplot scripts/plot/draw/fplot.m
@anchor{XREFfplot}
@deftypefn  {Function File} {} fplot (@var{fn}, @var{limits})
@deftypefnx {Function File} {} fplot (@dots{}, @var{tol})
@deftypefnx {Function File} {} fplot (@dots{}, @var{n})
@deftypefnx {Function File} {} fplot (@dots{}, @var{fmt})
@deftypefnx {Function File} {[@var{x}, @var{y}] =} fplot (@dots{})
Plot a function @var{fn} within the range defined by @var{limits}.

@var{fn} is a function handle, inline function, or string containing the
name of the function to evaluate.

The limits of the plot are of the form @w{@code{[@var{xlo}, @var{xhi}]}} or
@w{@code{[@var{xlo}, @var{xhi}, @var{ylo}, @var{yhi}]}}.

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

@var{tol} is the relative tolerance to use for the plot and defaults
to 2e-3 (.2%).

@var{n} is the minimum number of points to use.  When @var{n} is specified,
the maximum stepsize will be @code{@var{xhi} - @var{xlo} / @var{n}}.  More
than @var{n} points may still be used in order to meet the relative
tolerance requirement.

The @var{fmt} argument specifies the linestyle to be used by the plot
command.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

With no output arguments the results are immediately plotted.  With two
output arguments the 2-D plot data is returned.  The data can subsequently
be plotted manually with @code{plot (@var{x}, @var{y})}.

Example:

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

Note: @code{fplot} works best with continuous functions.  Functions with
discontinuities are unlikely to plot well.  This restriction may be removed
in the future.
@seealso{@ref{XREFezplot,,ezplot}, @ref{XREFplot,,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 ezplot scripts/plot/draw/ezplot.m
@anchor{XREFezplot}
@deftypefn  {Function File} {} ezplot (@var{f})
@deftypefnx {Function File} {} ezplot (@var{f2v})
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezplot (@dots{})

Plot the 2-D curve defined by the function @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{f2v} is a function of two variables then the implicit function
@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 points in each dimension.

For example:

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

If two functions are passed as inputs then the parametric function

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

@noindent
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
values of both @var{x} and @var{y}, or @var{t} for a parametric plot.  If
@var{dom} is a four element vector, then the minimum and maximum values are
@code{[xmin xmax ymin ymax]}.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the created line objects.

@seealso{@ref{XREFplot,,plot}, @ref{XREFezplot3,,ezplot3}, @ref{XREFezpolar,,ezpolar}, @ref{XREFezcontour,,ezcontour}, @ref{XREFezcontourf,,ezcontourf}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFezsurf,,ezsurf}, @ref{XREFezsurfc,,ezsurfc}}
@end deftypefn


@c ezcontour scripts/plot/draw/ezcontour.m
@anchor{XREFezcontour}
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezcontour (@dots{})

Plot 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 meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

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

@seealso{@ref{XREFcontour,,contour}, @ref{XREFezcontourf,,ezcontourf}, @ref{XREFezplot,,ezplot}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFezsurfc,,ezsurfc}}
@end deftypefn


@c ezcontourf scripts/plot/draw/ezcontourf.m
@anchor{XREFezcontourf}
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezcontourf (@dots{})

Plot 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 meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

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

@seealso{@ref{XREFcontourf,,contourf}, @ref{XREFezcontour,,ezcontour}, @ref{XREFezplot,,ezplot}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFezsurfc,,ezsurfc}}
@end deftypefn


@c ezpolar scripts/plot/draw/ezpolar.m
@anchor{XREFezpolar}
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezpolar (@dots{})

Plot a 2-D function in polar coordinates.

The function @var{f} is a string, inline function, or function handle with
a single argument.  The expected form of the function is
@code{@var{rho} = @var{f}(@var{theta})}.
By default the plot is over the domain @code{0 <= @var{theta} <= 2*pi}
with 500 points.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of @var{theta}.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

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

@seealso{@ref{XREFpolar,,polar}, @ref{XREFezplot,,ezplot}}
@end deftypefn


@node Two-dimensional Geometric Shapes
@subsubsection Two-dimensional Geometric Shapes

@c rectangle scripts/plot/draw/rectangle.m
@anchor{XREFrectangle}
@deftypefn  {Function File} {} rectangle ()
@deftypefnx {Function File} {} rectangle (@dots{}, "Position", @var{pos})
@deftypefnx {Function File} {} rectangle (@dots{}, "Curvature", @var{curv})
@deftypefnx {Function File} {} rectangle (@dots{}, "EdgeColor", @var{ec})
@deftypefnx {Function File} {} rectangle (@dots{}, "FaceColor", @var{fc})
@deftypefnx {Function File} {} rectangle (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} rectangle (@dots{})
Draw a rectangular patch defined by @var{pos} and @var{curv}.

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

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

If @var{curv} is a scalar, it represents the curvature of the shorter of the
two sides of the rectangle and the curvature of the other side is defined
by

@example
min (pos(1:2)) / max (pos(1:2)) * curv
@end example

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
rectangle object.
@end deftypefn
@seealso{@ref{XREFpatch,,patch}, @ref{XREFline,,line}, @ref{XREFcylinder,,cylinder}, @ref{XREFellipsoid,,ellipsoid}, @ref{XREFsphere,,sphere}}


@node Three-Dimensional Plots
@subsection Three-Dimensional Plots
@cindex plotting, three-dimensional

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 mesh scripts/plot/draw/mesh.m
@anchor{XREFmesh}
@deftypefn  {Function File} {} mesh (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} mesh (@var{z})
@deftypefnx {Function File} {} mesh (@dots{}, @var{c})
@deftypefnx {Function File} {} mesh (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} mesh (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} mesh (@dots{})
Plot a 3-D wireframe mesh.

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

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@seealso{@ref{XREFezmesh,,ezmesh}, @ref{XREFmeshc,,meshc}, @ref{XREFmeshz,,meshz}, @ref{XREFtrimesh,,trimesh}, @ref{XREFcontour,,contour}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}}
@end deftypefn


@c meshc scripts/plot/draw/meshc.m
@anchor{XREFmeshc}
@deftypefn  {Function File} {} meshc (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} meshc (@var{z})
@deftypefnx {Function File} {} meshc (@dots{}, @var{c})
@deftypefnx {Function File} {} meshc (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} meshc (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} meshc (@dots{})
Plot a 3-D wireframe mesh with underlying contour lines.

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

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle to the created surface object and to the created contour plot.

@seealso{@ref{XREFezmeshc,,ezmeshc}, @ref{XREFmesh,,mesh}, @ref{XREFmeshz,,meshz}, @ref{XREFcontour,,contour}, @ref{XREFsurfc,,surfc}, @ref{XREFsurface,,surface}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}}
@end deftypefn


@c meshz scripts/plot/draw/meshz.m
@anchor{XREFmeshz}
@deftypefn  {Function File} {} meshz (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} meshz (@var{z})
@deftypefnx {Function File} {} meshz (@dots{}, @var{c})
@deftypefnx {Function File} {} meshz (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} meshz (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} meshz (@dots{})
Plot a 3-D wireframe mesh with a surrounding curtain.

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

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@seealso{@ref{XREFmesh,,mesh}, @ref{XREFmeshc,,meshc}, @ref{XREFcontour,,contour}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}, @ref{XREFwaterfall,,waterfall}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}}
@end deftypefn


@c hidden scripts/plot/appearance/hidden.m
@anchor{XREFhidden}
@deftypefn  {Command} {} hidden
@deftypefnx {Command} {} hidden "on"
@deftypefnx {Command} {} hidden "off"
@deftypefnx {Function File} {@var{mode} =} hidden (@dots{})
Control mesh hidden line removal.

When called with no argument the hidden line removal state is toggled.
When called with one of the modes @qcode{"on"} or @qcode{"off"} the state
is set accordingly.

The optional output argument @var{mode} is the current state.

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

@seealso{@ref{XREFmesh,,mesh}, @ref{XREFmeshc,,meshc}, @ref{XREFmeshz,,meshz}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFtrimesh,,trimesh}, @ref{XREFwaterfall,,waterfall}}
@end deftypefn


@c surf scripts/plot/draw/surf.m
@anchor{XREFsurf}
@deftypefn  {Function File} {} surf (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surf (@var{z})
@deftypefnx {Function File} {} surf (@dots{}, @var{c})
@deftypefnx {Function File} {} surf (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} surf (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} surf (@dots{})
Plot a 3-D surface mesh.

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

The color of the surface is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the surface can be specified independently of
@var{z} by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Note: The exact appearance of the surface can be controlled with the
@code{shading} command or by using @code{set} to control surface object
properties.
@seealso{@ref{XREFezsurf,,ezsurf}, @ref{XREFsurfc,,surfc}, @ref{XREFsurfl,,surfl}, @ref{XREFsurfnorm,,surfnorm}, @ref{XREFtrisurf,,trisurf}, @ref{XREFcontour,,contour}, @ref{XREFmesh,,mesh}, @ref{XREFsurface,,surface}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}}
@end deftypefn


@c surfc scripts/plot/draw/surfc.m
@anchor{XREFsurfc}
@deftypefn  {Function File} {} surfc (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surfc (@var{z})
@deftypefnx {Function File} {} surfc (@dots{}, @var{c})
@deftypefnx {Function File} {} surfc (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} surfc (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} surfc (@dots{})
Plot a 3-D surface mesh with underlying contour lines.

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

The color of the surface is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the surface can be specified independently of
@var{z} by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Note: The exact appearance of the surface can be controlled with the
@code{shading} command or by using @code{set} to control surface object
properties.
@seealso{@ref{XREFezsurfc,,ezsurfc}, @ref{XREFsurf,,surf}, @ref{XREFsurfl,,surfl}, @ref{XREFsurfnorm,,surfnorm}, @ref{XREFtrisurf,,trisurf}, @ref{XREFcontour,,contour}, @ref{XREFmesh,,mesh}, @ref{XREFsurface,,surface}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}}
@end deftypefn


@c surfl scripts/plot/draw/surfl.m
@anchor{XREFsurfl}
@deftypefn  {Function File} {} surfl (@var{z})
@deftypefnx {Function File} {} surfl (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surfl (@dots{}, @var{lsrc})
@deftypefnx {Function File} {} surfl (@var{x}, @var{y}, @var{z}, @var{lsrc}, @var{P})
@deftypefnx {Function File} {} surfl (@dots{}, "cdata")
@deftypefnx {Function File} {} surfl (@dots{}, "light")
@deftypefnx {Function File} {} surfl (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} surfl (@dots{})

Plot a 3-D surface using shading based on various lighting models.

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

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

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

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

@table @asis
@item @qcode{"AM"} strength of ambient light

@item @qcode{"D"} strength of diffuse reflection

@item @qcode{"SP"} strength of specular reflection

@item @qcode{"EXP"} specular exponent
@end table

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Example:

@example
@group
colormap (bone (64));
surfl (peaks);
shading interp;
@end group
@end example
@seealso{@ref{XREFdiffuse,,diffuse}, @ref{XREFspecular,,specular}, @ref{XREFsurf,,surf}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}}
@end deftypefn


@c surfnorm scripts/plot/draw/surfnorm.m
@anchor{XREFsurfnorm}
@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:rows (@var{z}),
                   1:columns (@var{z}));
@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{XREFsurf,,surf}, @ref{XREFquiver3,,quiver3}}
@end deftypefn


@c isosurface scripts/plot/draw/isosurface.m
@anchor{XREFisosurface}
@deftypefn  {Function File} {[@var{fv}] =} isosurface (@var{val}, @var{iso})
@deftypefnx {Function File} {[@var{fv}] =} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso})
@deftypefnx {Function File} {[@var{fv}] =} isosurface (@dots{}, "noshare", "verbose")
@deftypefnx {Function File} {[@var{fvc}] =} isosurface (@dots{}, @var{col})
@deftypefnx {Function File} {[@var{f}, @var{v}] =} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso})
@deftypefnx {Function File} {[@var{f}, @var{v}, @var{c}] =} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso}, @var{col})
@deftypefnx {Function File} {} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso}, @var{col}, @var{opt})

If called with one output argument and the first input argument
@var{val} is a three-dimensional array that contains the data of an
isosurface geometry and the second input argument @var{iso} keeps the
isovalue as a scalar value then return a structure array @var{fv}
that contains the fields @var{Faces} and @var{Vertices} at computed
points @command{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}.  The output
argument @var{fv} can directly be taken as an input argument for the
@command{patch} function.

If called with further input arguments @var{x}, @var{y} and @var{z}
which are three--dimensional arrays with the same size than @var{val}
then the volume data is taken at those given points.

The string input argument @qcode{"noshare"} is only for compatibility and
has no effect.  If given the string input argument
@qcode{"verbose"} then print messages to the command line interface about the
current progress.

If called with the input argument @var{col} which is a
three-dimensional array of the same size than @var{val} then take
those values for the interpolation of coloring the isosurface
geometry.  Add the field @var{FaceVertexCData} to the structure
array @var{fv}.

If called with two or three output arguments then return the
information about the faces @var{f}, vertices @var{v} and color data
@var{c} as separate arrays instead of a single structure array.

If called with no output argument then directly process the
isosurface geometry with the @command{patch} command.

For example,

@example
@group
[x, y, z] = meshgrid (1:5, 1:5, 1:5);
val = rand (5, 5, 5);
isosurface (x, y, z, val, .5);
@end group
@end example

@noindent
will directly draw a random isosurface geometry in a graphics window.
Another example for an isosurface geometry with different additional
coloring
@c Set example in small font to prevent overfull line

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

subplot (2,2,1); view (-38, 20);
[f, v] = isosurface (x, y, z, c, iso);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none");
set (gca, "PlotBoxAspectRatioMode", "manual", ...
          "PlotBoxAspectRatio", [1 1 1]);
# set (p, "FaceColor", "green", "FaceLighting", "phong");
# light ("Position", [1 1 5]); # Available with the JHandles package

subplot (2,2,2); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "blue");
set (gca, "PlotBoxAspectRatioMode", "manual", ...
          "PlotBoxAspectRatio", [1 1 1]);
# set (p, "FaceColor", "none", "FaceLighting", "phong");
# light ("Position", [1 1 5]);

subplot (2,2,3); view (-38, 20);
[f, v, c] = isosurface (x, y, z, c, iso, y);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", c, ...
           "FaceColor", "interp", "EdgeColor", "none");
set (gca, "PlotBoxAspectRatioMode", "manual", ...
          "PlotBoxAspectRatio", [1 1 1]);
# set (p, "FaceLighting", "phong");
# light ("Position", [1 1 5]);

subplot (2,2,4); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", c, ...
           "FaceColor", "interp", "EdgeColor", "blue");
set (gca, "PlotBoxAspectRatioMode", "manual", ...
          "PlotBoxAspectRatio", [1 1 1]);
# set (p, "FaceLighting", "phong");
# light ("Position", [1 1 5]);
@end smallexample

@seealso{@ref{XREFisonormals,,isonormals}, @ref{XREFisocolors,,isocolors}}
@end deftypefn


@c isonormals scripts/plot/draw/isonormals.m
@anchor{XREFisonormals}
@deftypefn  {Function File} {[@var{n}] =} isonormals (@var{val}, @var{v})
@deftypefnx {Function File} {[@var{n}] =} isonormals (@var{val}, @var{p})
@deftypefnx {Function File} {[@var{n}] =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{v})
@deftypefnx {Function File} {[@var{n}] =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{p})
@deftypefnx {Function File} {[@var{n}] =} isonormals (@dots{}, "negate")
@deftypefnx {Function File} {} isonormals (@dots{}, @var{p})

If called with one output argument and the first input argument
@var{val} is a three-dimensional array that contains the data for an
isosurface geometry and the second input argument @var{v} keeps the
vertices of an isosurface then return the normals @var{n} in form of
a matrix with the same size than @var{v} at computed points
@command{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}.  The output argument
@var{n} can be taken to manually set @var{VertexNormals} of a patch.

If called with further input arguments @var{x}, @var{y} and @var{z}
which are three--dimensional arrays with the same size than @var{val}
then the volume data is taken at those given points.  Instead of the
vertices data @var{v} a patch handle @var{p} can be passed to this
function.

If given the string input argument @qcode{"negate"} as last input argument
then compute the reverse vector normals of an isosurface geometry.

If no output argument is given then directly redraw the patch that is
given by the patch handle @var{p}.

For example:
@c Set example in small font to prevent overfull line

@smallexample
function [] = isofinish (p)
  set (gca, "PlotBoxAspectRatioMode", "manual", ...
            "PlotBoxAspectRatio", [1 1 1]);
  set (p, "VertexNormals", -get (p,"VertexNormals")); # Revert normals
  set (p, "FaceColor", "interp");
  ## set (p, "FaceLighting", "phong");
  ## light ("Position", [1 1 5]); # Available with JHandles
endfunction

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

subplot (2,2,1); view (-38, 20);
[f, v, cdat] = isosurface (x, y, z, c, iso, y);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ...
           "FaceColor", "interp", "EdgeColor", "none");
isofinish (p); ## Call user function isofinish

subplot (2,2,2); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ...
           "FaceColor", "interp", "EdgeColor", "none");
isonormals (x, y, z, c, p); # Directly modify patch
isofinish (p);

subplot (2,2,3); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ...
           "FaceColor", "interp", "EdgeColor", "none");
n = isonormals (x, y, z, c, v); # Compute normals of isosurface
set (p, "VertexNormals", n);    # Manually set vertex normals
isofinish (p);

subplot (2,2,4); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ...
           "FaceColor", "interp", "EdgeColor", "none");
isonormals (x, y, z, c, v, "negate"); # Use reverse directly
isofinish (p);
@end smallexample

@seealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisocolors,,isocolors}}
@end deftypefn


@c isocolors scripts/plot/draw/isocolors.m
@anchor{XREFisocolors}
@deftypefn  {Function File} {[@var{cd}] =} isocolors (@var{c}, @var{v})
@deftypefnx {Function File} {[@var{cd}] =} isocolors (@var{x}, @var{y}, @var{z}, @var{c}, @var{v})
@deftypefnx {Function File} {[@var{cd}] =} isocolors (@var{x}, @var{y}, @var{z}, @var{r}, @var{g}, @var{b}, @var{v})
@deftypefnx {Function File} {[@var{cd}] =} isocolors (@var{r}, @var{g}, @var{b}, @var{v})
@deftypefnx {Function File} {[@var{cd}] =} isocolors (@dots{}, @var{p})
@deftypefnx {Function File} {} isocolors (@dots{})

If called with one output argument and the first input argument
@var{c} is a three-dimensional array that contains color values and
the second input argument @var{v} keeps the vertices of a geometry
then return a matrix @var{cd} with color data information for the
geometry at computed points
@command{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}.  The output argument
@var{cd} can be taken to manually set FaceVertexCData of a patch.

If called with further input arguments @var{x}, @var{y} and @var{z}
which are three--dimensional arrays of the same size than @var{c}
then the color data is taken at those given points.  Instead of the
color data @var{c} this function can also be called with RGB values
@var{r}, @var{g}, @var{b}.  If input argumnets @var{x}, @var{y},
@var{z} are not given then again @command{meshgrid} computed values
are taken.

Optionally, the patch handle @var{p} can be given as the last input
argument to all variations of function calls instead of the vertices
data @var{v}.  Finally, if no output argument is given then directly
change the colors of a patch that is given by the patch handle
@var{p}.

For example:

@example
function [] = isofinish (p)
  set (gca, "PlotBoxAspectRatioMode", "manual", ...
            "PlotBoxAspectRatio", [1 1 1]);
  set (p, "FaceColor", "interp");
  ## set (p, "FaceLighting", "flat");
  ## light ("Position", [1 1 5]); ## Available with JHandles
endfunction

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

subplot (2,2,1); view (-38, 20);
[f, v] = isosurface (x, y, z, c, iso);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none");
cdat = rand (size (c));       # Compute random patch color data
isocolors (x, y, z, cdat, p); # Directly set colors of patch
isofinish (p);                # Call user function isofinish

subplot (2,2,2); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none");
[r, g, b] = meshgrid (lin, 2-lin, 2-lin);
cdat = isocolors (x, y, z, c, v); # Compute color data vertices
set (p, "FaceVertexCData", cdat); # Set color data manually
isofinish (p);

subplot (2,2,3); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none");
cdat = isocolors (r, g, b, c, p); # Compute color data patch
set (p, "FaceVertexCData", cdat); # Set color data manually
isofinish (p);

subplot (2,2,4); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none");
r = g = b = repmat ([1:N] / N, [N, 1, N]); # Black to white
cdat = isocolors (x, y, z, r, g, b, v);
set (p, "FaceVertexCData", cdat);
isofinish (p);
@end example

@seealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisonormals,,isonormals}}
@end deftypefn


@c shrinkfaces scripts/plot/draw/shrinkfaces.m
@anchor{XREFshrinkfaces}
@deftypefn  {Function File} {} shrinkfaces (@var{p}, @var{sf})
@deftypefnx {Function File} {@var{nfv} =} shrinkfaces (@var{p}, @var{sf})
@deftypefnx {Function File} {@var{nfv} =} shrinkfaces (@var{fv}, @var{sf})
@deftypefnx {Function File} {@var{nfv} =} shrinkfaces (@var{f}, @var{v}, @var{sf})
@deftypefnx {Function File} {[@var{nf}, @var{nv}] =} shrinkfaces (@dots{})

Reduce the faces area for a given patch, structure or explicit faces
and points matrices by a scale factor @var{sf}.  The structure
@var{fv} must contain the fields @qcode{"faces"} and @qcode{"vertices"}. 
If the factor @var{sf} is omitted then a default of 0.3 is used.

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

If called with one output argument, return a structure with fields
@qcode{"faces"}, @qcode{"vertices"}, and @qcode{"facevertexcdata"}
containing the data after shrinking which can then directly be used as an
input argument for the @code{patch} function.

Performing the shrinking on faces which are not convex can lead to
undesired results.

For example,

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

@noindent
draws a triangulated 3/4 circle and the corresponding shrunken
version.
@seealso{@ref{XREFpatch,,patch}}
@end deftypefn


@c diffuse scripts/plot/appearance/diffuse.m
@anchor{XREFdiffuse}
@deftypefn {Function File} {} diffuse (@var{sx}, @var{sy}, @var{sz}, @var{lv})
Calculate diffuse reflection strength of a surface defined by the normal
vector elements @var{sx}, @var{sy}, @var{sz}.

The light source location vector @var{lv} can be given as 2-element vector
[azimuth, elevation] in degrees or as 3-element vector [lx, ly, lz].
@seealso{@ref{XREFspecular,,specular}, @ref{XREFsurfl,,surfl}}
@end deftypefn


@c specular scripts/plot/appearance/specular.m
@anchor{XREFspecular}
@deftypefn  {Function File} {} specular (@var{sx}, @var{sy}, @var{sz}, @var{lv}, @var{vv})
@deftypefnx {Function File} {} specular (@var{sx}, @var{sy}, @var{sz}, @var{lv}, @var{vv}, @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 source location and viewer location vectors can be specified using
parameter @var{lv} and @var{vv} respectively.  The location vectors can
given as 2-element vectors [azimuth, elevation] in degrees or as 3-element
vectors [x, y, z].

An optional sixth argument describes the specular exponent (spread) @var{se}.
@seealso{@ref{XREFdiffuse,,diffuse}, @ref{XREFsurfl,,surfl}}
@end deftypefn


@c meshgrid scripts/plot/util/meshgrid.m
@anchor{XREFmeshgrid}
@deftypefn  {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@var{x}, @var{y})
@deftypefnx {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})
@deftypefnx {Function File} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x})
Given vectors of @var{x} and @var{y} coordinates, return matrices @var{xx}
and @var{yy} corresponding to a full 2-D grid.

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

If the optional @var{z} input is given, or @var{zz} is requested, then the
output will be a full 3-D grid.

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

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

Programming Note: @code{meshgrid} is restricted to 2-D or 3-D grid
generation.  The @code{ndgrid} function will generate 1-D through N-D
grids.  However, the functions are not completely equivalent.  If @var{x}
is a vector of length M and @var{y} is a vector of length N, then
@code{meshgrid} will produce an output grid which is NxM@.  @code{ndgrid}
will produce an output which is @nospell{MxN} (transpose) for the same
input.  Some core functions expect @code{meshgrid} input and others expect
@code{ndgrid} input.  Check the documentation for the function in question
to determine the proper input format.
@seealso{@ref{XREFndgrid,,ndgrid}, @ref{XREFmesh,,mesh}, @ref{XREFcontour,,contour}, @ref{XREFsurf,,surf}}
@end deftypefn


@c ndgrid scripts/plot/util/ndgrid.m
@anchor{XREFndgrid}
@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 to 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})

Programming Note: @code{ndgrid} is very similar to the function
@code{meshgrid} except that the first two dimensions are transposed in
comparison to @code{meshgrid}.  Some core functions expect @code{meshgrid}
input and others expect @code{ndgrid} input.  Check the documentation for
the function in question to determine the proper input format.
@seealso{@ref{XREFmeshgrid,,meshgrid}}
@end deftypefn


@c plot3 scripts/plot/draw/plot3.m
@anchor{XREFplot3}
@deftypefn  {Function File} {} plot3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} plot3 (@var{x}, @var{y}, @var{z}, @var{prop}, @var{value}, @dots{})
@deftypefnx {Function File} {} plot3 (@var{x}, @var{y}, @var{z}, @var{fmt})
@deftypefnx {Function File} {} plot3 (@var{x}, @var{cplx})
@deftypefnx {Function File} {} plot3 (@var{cplx})
@deftypefnx {Function File} {} plot3 (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} plot3 (@dots{})
Produce 3-D 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 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{cplx})
@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{cplx})
@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

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

@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{XREFezplot3,,ezplot3}, @ref{XREFplot,,plot}}
@end deftypefn


@c view scripts/plot/appearance/view.m
@anchor{XREFview}
@deftypefn  {Function File} {} view (@var{azimuth}, @var{elevation})
@deftypefnx {Function File} {} view ([@var{azimuth} @var{elevation}])
@deftypefnx {Function File} {} view ([@var{x} @var{y} @var{z}])
@deftypefnx {Function File} {} view (2)
@deftypefnx {Function File} {} view (3)
@deftypefnx {Function File} {} view (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{azimuth}, @var{elevation}] =} view ()
Query or set the viewpoint for the current axes.

The parameters @var{azimuth} and @var{elevation} can be given as two
arguments or as 2-element vector.  The viewpoint can also be specified with
Cartesian coordinates @var{x}, @var{y}, and @var{z}.

The call @code{view (2)} sets the viewpoint to @w{@var{azimuth} = 0}
and @w{@var{elevation} = 90}, which is the default for 2-D graphs.

The call @code{view (3)} sets the viewpoint to @w{@var{azimuth} = -37.5}
and @w{@var{elevation} = 30}, which is the default for 3-D graphs.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

If no inputs are given, return the current @var{azimuth} and @var{elevation}.
@end deftypefn


@c slice scripts/plot/draw/slice.m
@anchor{XREFslice}
@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} {} slice (@dots{}, @var{method})
@deftypefnx {Function File} {} slice (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} slice (@dots{})
Plot slices of 3-D 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 @qcode{"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 @asis
@item @qcode{"nearest"}
Return the nearest neighbor.

@item @qcode{"linear"}
Linear interpolation from nearest neighbors.

@item @qcode{"cubic"}
Cubic interpolation from four nearest neighbors (not implemented yet).

@item @qcode{"spline"}
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

The default method is @qcode{"linear"}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

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{XREFinterp3,,interp3}, @ref{XREFsurface,,surface}, @ref{XREFpcolor,,pcolor}}
@end deftypefn


@c ribbon scripts/plot/draw/ribbon.m
@anchor{XREFribbon}
@deftypefn  {Function File} {} ribbon (@var{y})
@deftypefnx {Function File} {} ribbon (@var{x}, @var{y})
@deftypefnx {Function File} {} ribbon (@var{x}, @var{y}, @var{width})
@deftypefnx {Function File} {} ribbon (@var{hax}, @dots{})
@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 (@code{1:rows (Y)}).

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the surface objects representing each ribbon.
@seealso{@ref{XREFsurface,,surface}, @ref{XREFwaterfall,,waterfall}}
@end deftypefn


@c shading scripts/plot/appearance/shading.m
@anchor{XREFshading}
@deftypefn  {Function File} {} shading (@var{type})
@deftypefnx {Function File} {} shading (@var{hax}, @var{type})
Set the shading of patch or surface graphic objects.

Valid arguments for @var{type} are

@table @asis
@item @qcode{"flat"}
Single colored patches with invisible edges.

@item @qcode{"faceted"}
Single colored patches with visible edges.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.
@seealso{@ref{XREFfill,,fill}, @ref{XREFmesh,,mesh}, @ref{XREFpatch,,patch}, @ref{XREFpcolor,,pcolor}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}, @ref{XREFhidden,,hidden}}
@end deftypefn


@c scatter3 scripts/plot/draw/scatter3.m
@anchor{XREFscatter3}
@deftypefn  {Function File} {} scatter3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s})
@deftypefnx {Function File} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}, @var{c})
@deftypefnx {Function File} {} scatter3 (@dots{}, @var{style})
@deftypefnx {Function File} {} scatter3 (@dots{}, "filled")
@deftypefnx {Function File} {} scatter3 (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} scatter3 (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} scatter3 (@dots{})
Draw a 3-D scatter plot.

A marker is plotted at each point defined by the coordinates in the vectors
@var{x}, @var{y}, and @var{z}.

The size of the markers is determined by @var{s}, which can be a scalar
or a vector of the same length as @var{x}, @var{y}, and @var{z}.  If @var{s}
is not given, or is an empty matrix, then a default value of 8 points is
used.

The color of the markers is determined by @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 an @nospell{Nx3} matrix defining
the RGB color of each marker 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 no marker is specified it defaults to @qcode{"o"} or circles.
If the argument @qcode{"filled"} is given then the markers are filled.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the hggroup
object representing the points.

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

@seealso{@ref{XREFscatter,,scatter}, @ref{XREFpatch,,patch}, @ref{XREFplot,,plot}}
@end deftypefn


@c waterfall scripts/plot/draw/waterfall.m
@anchor{XREFwaterfall}
@deftypefn  {Function File} {} waterfall (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} waterfall (@var{z})
@deftypefnx {Function File} {} waterfall (@dots{}, @var{c})
@deftypefnx {Function File} {} waterfall (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} waterfall (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} waterfall (@dots{})
Plot a 3-D waterfall plot.

A waterfall plot is similar to a @code{meshz} plot except only
mesh lines for the rows of @var{z} (x-values) are shown.

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

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@seealso{@ref{XREFmeshz,,meshz}, @ref{XREFmesh,,mesh}, @ref{XREFmeshc,,meshc}, @ref{XREFcontour,,contour}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}, @ref{XREFribbon,,ribbon}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}}
@end deftypefn


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

@node Aspect Ratio
@subsubsection Aspect Ratio

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

@c daspect scripts/plot/appearance/daspect.m
@anchor{XREFdaspect}
@deftypefn  {Function File} {@var{data_aspect_ratio} =} daspect ()
@deftypefnx {Function File} {} daspect (@var{data_aspect_ratio})
@deftypefnx {Function File} {} daspect (@var{mode})
@deftypefnx {Function File} {@var{data_aspect_ratio_mode} =} daspect ("mode")
@deftypefnx {Function File} {} daspect (@var{hax}, @dots{})
Query or set the data aspect ratio of the current axes.

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

@code{daspect (@var{mode})}

Set the data aspect ratio mode of the current axes.  @var{mode} is
either @qcode{"auto"} or @qcode{"manual"}.

@code{daspect (@qcode{"mode"})}

Return the data aspect ratio mode of the current axes.

@code{daspect (@var{hax}, @dots{})}

Operate on the axes in handle @var{hax} instead of the current axes.

@seealso{@ref{XREFaxis,,axis}, @ref{XREFpbaspect,,pbaspect}, @ref{XREFxlim,,xlim}, @ref{XREFylim,,ylim}, @ref{XREFzlim,,zlim}}
@end deftypefn


@c pbaspect scripts/plot/appearance/pbaspect.m
@anchor{XREFpbaspect}
@deftypefn  {Function File} {@var{plot_box_aspect_ratio} =} pbaspect ( )
@deftypefnx {Function File} {} pbaspect (@var{plot_box_aspect_ratio})
@deftypefnx {Function File} {} pbaspect (@var{mode})
@deftypefnx {Function File} {@var{plot_box_aspect_ratio_mode} =} pbaspect ("mode")
@deftypefnx {Function File} {} pbaspect (@var{hax}, @dots{})

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

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

@code{pbaspect(@var{mode})}

Set the plot box aspect ratio mode of the current axes.  @var{mode} is
either @qcode{"auto"} or @qcode{"manual"}.

@code{pbaspect ("mode")}

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

@code{pbaspect (@var{hax}, @dots{})}

Operate on the axes in handle @var{hax} instead of the current axes.

@seealso{@ref{XREFaxis,,axis}, @ref{XREFdaspect,,daspect}, @ref{XREFxlim,,xlim}, @ref{XREFylim,,ylim}, @ref{XREFzlim,,zlim}}
@end deftypefn


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

@c ezplot3 scripts/plot/draw/ezplot3.m
@anchor{XREFezplot3}
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezplot3 (@dots{})

Plot a parametrically defined curve in three dimensions.

@var{fx}, @var{fy}, and @var{fz} are strings, inline functions,
or function handles with one argument defining the function.  By
default the plot is over the domain @code{0 <= @var{t} <= 2*pi}
with 500 points.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of @var{t}.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

@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{XREFplot3,,plot3}, @ref{XREFezplot,,ezplot}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezsurf,,ezsurf}}
@end deftypefn


@c ezmesh scripts/plot/draw/ezmesh.m
@anchor{XREFezmesh}
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezmesh (@dots{})

Plot 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 meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points 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 @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

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

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created 
surface object.

Example 1: 2-argument function

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

Example 2: parametrically defined function

@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{XREFmesh,,mesh}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFezplot,,ezplot}, @ref{XREFezsurf,,ezsurf}, @ref{XREFezsurfc,,ezsurfc}, @ref{XREFhidden,,hidden}}
@end deftypefn


@c ezmeshc scripts/plot/draw/ezmeshc.m
@anchor{XREFezmeshc}
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezmeshc (@dots{})

Plot 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 meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points 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 @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

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

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle for the created mesh plot and a second handle for the created contour
plot.

Example: 2-argument function

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

@seealso{@ref{XREFmeshc,,meshc}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezplot,,ezplot}, @ref{XREFezsurf,,ezsurf}, @ref{XREFezsurfc,,ezsurfc}, @ref{XREFhidden,,hidden}}
@end deftypefn


@c ezsurf scripts/plot/draw/ezsurf.m
@anchor{XREFezsurf}
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezsurf (@dots{})

Plot 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 meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points 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 @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

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

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Example 1: 2-argument function

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

Example 2: parametrically defined function

@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{XREFsurf,,surf}, @ref{XREFezsurfc,,ezsurfc}, @ref{XREFezplot,,ezplot}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFshading,,shading}}
@end deftypefn


@c ezsurfc scripts/plot/draw/ezsurfc.m
@anchor{XREFezsurfc}
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezsurfc (@dots{})

Plot 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 meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points 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 @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

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

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle for the created surface plot and a second handle for the created
contour plot.

Example:

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

@seealso{@ref{XREFsurfc,,surfc}, @ref{XREFezsurf,,ezsurf}, @ref{XREFezplot,,ezplot}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFshading,,shading}}
@end deftypefn


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

@c cylinder scripts/plot/draw/cylinder.m
@anchor{XREFcylinder}
@deftypefn  {Command} {} cylinder
@deftypefnx {Function File} {} cylinder (@var{r})
@deftypefnx {Function File} {} cylinder (@var{r}, @var{n})
@deftypefnx {Function File} {} cylinder (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} cylinder (@dots{})
Plot a 3-D unit cylinder.

The optional input @var{r} is a vector specifying the radius along the
unit z-axis.  The default is [1 1] indicating radius 1 at @code{Z == 0}
and at @code{Z == 1}.

The optional input @var{n} determines the number of faces around the
the circumference of the cylinder.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

If outputs are requested @code{cylinder} returns three matrices in
@code{meshgrid} format, such that @code{surf (@var{x}, @var{y}, @var{z})}
generates a unit cylinder.

Example:

@example
@group
[x, y, z] = cylinder (10:-1:0, 50);
surf (x, y, z);
title ("a cone");
@end group
@end example
@seealso{@ref{XREFellipsoid,,ellipsoid}, @ref{XREFrectangle,,rectangle}, @ref{XREFsphere,,sphere}}
@end deftypefn


@c sphere scripts/plot/draw/sphere.m
@anchor{XREFsphere}
@deftypefn  {Function File} {} sphere ()
@deftypefnx {Function File} {} sphere (@var{n})
@deftypefnx {Function File} {} sphere (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} sphere (@dots{})
Plot a 3-D unit sphere.

The optional input @var{n} determines the number of faces around the
the circumference of the sphere.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

If outputs are requested @code{sphere} returns three matrices in
@code{meshgrid} format such that @code{surf (@var{x}, @var{y}, @var{z})}
generates a unit sphere.

Example:

@example
@group
[x, y, z] = sphere (40);
surf (3*x, 3*y, 3*z);
axis equal;
title ("sphere of radius 3");
@end group
@end example
@seealso{@ref{XREFcylinder,,cylinder}, @ref{XREFellipsoid,,ellipsoid}, @ref{XREFrectangle,,rectangle}}
@end deftypefn


@c ellipsoid scripts/plot/draw/ellipsoid.m
@anchor{XREFellipsoid}
@deftypefn  {Function File} {} ellipsoid (@var{xc}, @var{yc}, @var{zc}, @var{xr}, @var{yr}, @var{zr}, @var{n})
@deftypefnx {Function File} {} ellipsoid (@dots{}, @var{n})
@deftypefnx {Function File} {} ellipsoid (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} ellipsoid (@dots{})
Plot a 3-D ellipsoid.

The inputs @var{xc}, @var{yc}, @var{zc} specify the center of the ellipsoid.
The inputs @var{xr}, @var{yr}, @var{zr} specify the semi-major axis lengths.

The optional input @var{n} determines the number of faces around the
the circumference of the cylinder.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

If outputs are requested @code{ellipsoid} returns three matrices in
@code{meshgrid} format, such that @code{surf (@var{x}, @var{y}, @var{z})}
generates the ellipsoid.
@seealso{@ref{XREFcylinder,,cylinder}, @ref{XREFrectangle,,rectangle}, @ref{XREFsphere,,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 title scripts/plot/appearance/title.m
@anchor{XREFtitle}
@deftypefn  {Function File} {} title (@var{string})
@deftypefnx {Function File} {} title (@var{string}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} title (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} title (@dots{})
Specify the string used as a title for the current axis.

An optional list of @var{property}/@var{value} pairs can be used to change
the appearance of the created title text object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created text
object.
@seealso{@ref{XREFxlabel,,xlabel}, @ref{XREFylabel,,ylabel}, @ref{XREFzlabel,,zlabel}, @ref{XREFtext,,text}}
@end deftypefn


@c legend scripts/plot/appearance/legend.m
@anchor{XREFlegend}
@deftypefn  {Function File} {} legend (@var{str1}, @var{str2}, @dots{})
@deftypefnx {Function File} {} legend (@var{matstr})
@deftypefnx {Function File} {} legend (@var{cellstr})
@deftypefnx {Function File} {} legend (@dots{}, "location", @var{pos})
@deftypefnx {Function File} {} legend (@dots{}, "orientation", @var{orient})
@deftypefnx {Function File} {} legend (@var{hax}, @dots{})
@deftypefnx {Function File} {} legend (@var{hobjs}, @dots{})
@deftypefnx {Function File} {} legend (@var{hax}, @var{hobjs}, @dots{})
@deftypefnx {Function File} {} legend ("@var{option}")
@deftypefnx {Function File} {[@var{hleg}, @var{hleg_obj}, @var{hplot}, @var{labels}] =} legend (@dots{})

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.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.  If the handles,
@var{hobjs}, are not specified then the legend's strings will be associated
with the axes' descendants.  @code{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
@headitem @tab pos @tab location of the legend
@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

The optional parameter @var{orient} determines if the key elements
are placed vertically or horizontally.  The allowed values are
@qcode{"vertical"} (default) or @qcode{"horizontal"}.

The following customizations are available using @var{option}:

@table @asis
@item @qcode{"show"}
  Show legend on the plot

@item @qcode{"hide"}
  Hide legend on the plot

@item @qcode{"toggle"}
  Toggles between @qcode{"hide"} and @qcode{"show"}

@item @qcode{"boxon"}
  Show a box around legend (default)

@item @qcode{"boxoff"}
  Hide the box around legend

@item @qcode{"right"}
  Place label text to the right of the keys (default)

@item @qcode{"left"}
  Place label text to the left of the keys

@item @qcode{"off"}
  Delete the legend object
@end table

The optional output values are

@table @var
@item hleg
  The graphics handle of the legend object.

@item hleg_obj
  Graphics handles to the text and line objects which make up the legend.

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

@item labels
  A cell array of strings of the labels in the legend.
@end table

The legend label text is either provided in the call to @code{legend} or
is taken from the DisplayName property of graphics objects.  If no
labels or DisplayNames are available, then the label text is simply
@qcode{"data1"}, @qcode{"data2"}, @dots{}, @nospell{@qcode{"dataN"}}.

Implementation Note: A legend is implemented as an additional axes object
of the current figure with the @qcode{"tag"} set to @qcode{"legend"}.
Properties of the legend object may be manipulated directly by using
@code{set}.
@end deftypefn


@c text scripts/plot/appearance/text.m
@anchor{XREFtext}
@deftypefn  {Function File} {} text (@var{x}, @var{y}, @var{string})
@deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{z}, @var{string})
@deftypefnx {Function File} {} text (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} text (@dots{})
Create a text object with text @var{string} at position @var{x}, @var{y},
(@var{z}) on the current axes.

Multiple locations can be specified if @var{x}, @var{y}, (@var{z}) are
vectors.  Multiple strings can be specified with a character matrix or
a cell array of strings.

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

The optional return value @var{h} is a vector of graphics handles to the
created text objects.
@seealso{@ref{XREFgtext,,gtext}, @ref{XREFtitle,,title}, @ref{XREFxlabel,,xlabel}, @ref{XREFylabel,,ylabel}, @ref{XREFzlabel,,zlabel}}
@end deftypefn


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

@anchor{XREFylabel}
@anchor{XREFzlabel}
@c xlabel scripts/plot/appearance/xlabel.m
@anchor{XREFxlabel}
@deftypefn  {Function File} {} xlabel (@var{string})
@deftypefnx {Function File} {} xlabel (@var{string}, @var{property}, @var{val}, @dots{})
@deftypefnx {Function File} {} xlabel (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} xlabel (@dots{})
Specify the string used to label the x-axis of the current axis.

An optional list of @var{property}/@var{value} pairs can be used to change
the properties of the created text label.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created text
object.
@seealso{@ref{XREFylabel,,ylabel}, @ref{XREFzlabel,,zlabel}, @ref{XREFdatetick,,datetick}, @ref{XREFtitle,,title}, @ref{XREFtext,,text}}
@end deftypefn


@c clabel scripts/plot/appearance/clabel.m
@anchor{XREFclabel}
@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 (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} clabel (@dots{})
Add labels to the contours of a contour plot.

The contour levels are specified by the contour matrix @var{c} which is
returned by @code{contour}, @code{contourc}, @code{contourf}, and
@code{contour3}.  Contour labels are rotated to match the local line 
orientation and centered on the line.  The position of labels along the
contour line is chosen randomly.

If the argument @var{h} is a handle to a contour group object, then label
this plot rather than the one in the current axes returned by @code{gca}.

By default, all contours are labeled.  However, the contours to label can be
specified by the vector @var{v}.  If the @qcode{"manual"} argument is
given then the contours to label can be selected with the mouse.

Additional property/value pairs that are valid properties of text objects
can be given and are passed to the underlying text objects.  Moreover,
the contour group property @qcode{"LabelSpacing"} is available which
determines the spacing between labels on a contour to be specified.  The
default is 144 points, or 2 inches.

The optional return value @var{h} is a vector of graphics handles to
the text objects representing each label.
The @qcode{"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{XREFcontour,,contour}, @ref{XREFcontourf,,contourf}, @ref{XREFcontour3,,contour3}, @ref{XREFmeshc,,meshc}, @ref{XREFsurfc,,surfc}, @ref{XREFtext,,text}}
@end deftypefn


@c box scripts/plot/appearance/box.m
@anchor{XREFbox}
@deftypefn  {Command} {} box on
@deftypefnx {Command} {} box off
@deftypefnx {Command} {} box
@deftypefnx {Function File} {} box (@var{hax}, @dots{})
Control display of the axis border.

The argument may be either @qcode{"on"} or @qcode{"off"}.  If it is
omitted, the current box state is toggled.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.
@seealso{@ref{XREFaxis,,axis}, @ref{XREFgrid,,grid}}
@end deftypefn


@c grid scripts/plot/appearance/grid.m
@anchor{XREFgrid}
@deftypefn  {Command} {} grid
@deftypefnx {Command} {} grid on
@deftypefnx {Command} {} grid off
@deftypefnx {Command} {} grid minor
@deftypefnx {Command} {} grid minor on
@deftypefnx {Command} {} grid minor off
@deftypefnx {Function File} {} grid (@var{hax}, @dots{})
Control the display of plot grid lines.

The function state input may be either @qcode{"on"} or @qcode{"off"}.
If it is omitted, the current grid state is toggled.

When the first argument is @qcode{"minor"} all subsequent commands
modify the minor grid rather than the major grid.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

To control the grid lines for an individual axis use the @code{set}
function.  For example:

@example
set (gca, "ygrid", "on");
@end example
@seealso{@ref{XREFaxis,,axis}, @ref{XREFbox,,box}}
@end deftypefn


@c colorbar scripts/plot/draw/colorbar.m
@anchor{XREFcolorbar}
@deftypefn  {Command} {} colorbar
@deftypefnx {Function File} {} colorbar (@var{loc})
@deftypefnx {Function File} {} colorbar (@var{delete_option})
@deftypefnx {Function File} {} colorbar (@var{hcb}, @dots{})
@deftypefnx {Function File} {} colorbar (@var{hax}, @dots{})
@deftypefnx {Function File} {} colorbar (@dots{}, "peer", @var{hax}, @dots{})
@deftypefnx {Function File} {} colorbar (@dots{}, "location", @var{loc}, @dots{})
@deftypefnx {Function File} {} colorbar (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} colorbar (@dots{})
Add a colorbar to the current axes.

A colorbar displays the current colormap along with numerical rulings
so that the color scale can be interpreted.

The optional input @var{loc} determines the location of the colorbar.
Valid values for @var{loc} are

@table @asis
@item @qcode{"EastOutside"}
Place the colorbar outside the plot to the right.  This is the default.

@item @qcode{"East"}
Place the colorbar inside the plot to the right.

@item @qcode{"WestOutside"}
Place the colorbar outside the plot to the left.

@item @qcode{"West"}
Place the colorbar inside the plot to the left.

@item @qcode{"NorthOutside"}
Place the colorbar above the plot.

@item @qcode{"North"}
Place the colorbar at the top of the plot.

@item @qcode{"SouthOutside"}
Place the colorbar under the plot.

@item @qcode{"South"}
Place the colorbar at the bottom of the plot.
@end table

To remove a colorbar from a plot use any one of the following keywords for
the @var{delete_option}: @qcode{"delete"}, @qcode{"hide"}, @qcode{"off"}.

If the argument @qcode{"peer"} is given, then the following argument is
treated as the axes handle in which to add the colorbar.  Alternatively,
If the first argument @var{hax} is an axes handle, then the colorbar is
added to this axis, rather than the current axes returned by @code{gca}.

If the first argument @var{hcb} is a handle to a colorbar object, then
operate on this colorbar directly.

Additional property/value pairs are passed directly to the underlying axes
object.

The optional return value @var{h} is a graphics handle to the created
colorbar object.

Implementation Note: A colorbar is created as an additional axes to the
current figure with the @qcode{"tag"} property set to @qcode{"colorbar"}. 
The created axes object has the extra property @qcode{"location"} which
controls the positioning of the colorbar.
@seealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@node Multiple Plots on One Page
@subsection Multiple Plots on One Page
@cindex plotting, multiple plots per figure

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 subplot scripts/plot/util/subplot.m
@anchor{XREFsubplot}
@deftypefn  {Function File} {} subplot (@var{rows}, @var{cols}, @var{index})
@deftypefnx {Function File} {} subplot (@var{rcn})
@deftypefnx {Function File} {} subplot (@var{hax})
@deftypefnx {Function File} {} subplot (@dots{}, "align")
@deftypefnx {Function File} {} subplot (@dots{}, "replace")
@deftypefnx {Function File} {} subplot (@dots{}, "position", @var{pos})
@deftypefnx {Function File} {} subplot (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{hax} =} subplot (@dots{})
Set up a plot grid with @var{rows} by @var{cols} subwindows and set the
current axes for plotting (@code{gca}) to the location given by @var{index}.

If only one numeric argument is supplied, then it must be a three digit
value specifying the number of rows in digit 1, the number of
columns in digit 2, and the plot index in digit 3.

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

For example, a plot with 2x3 grid will have plot indices running as follows:
@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

@example
@group
+-----+-----+-----+
|  1  |  2  |  3  |
+-----+-----+-----+
|  4  |  5  |  6  |
+-----+-----+-----+
@end group
@end example

@end ifnottex

@var{index} may also be a vector.  In this case, the new axis will enclose
the grid locations specified.  The first demo illustrates this:

@example
demo ("subplot", 1)
@end example

The index of the subplot to make active may also be specified by its axes
handle, @var{hax}, returned from a previous @code{subplot} command.

If the option @qcode{"align"} is given then the plot boxes of the subwindows
will align, but this may leave no room for axis tick marks or labels.

If the option @qcode{"replace"} is given then the subplot axis will be
reset, rather than just switching the current axis for plotting to the
requested subplot.

The @qcode{"position"} property can be used to exactly position the subplot
axes within the current figure.  The option @var{pos} is a 4-element vector
[x, y, width, height] that determines the location and size of the axes.
The values in @var{pos} are normalized in the range [0,1].

Any property/value pairs are passed directly to the underlying axes object.

If the output @var{hax} is requested, subplot returns the axis handle for
the subplot.  This is useful for modifying the properties of a subplot
using @code{set}.
@seealso{@ref{XREFaxes,,axes}, @ref{XREFplot,,plot}, @ref{XREFgca,,gca}, @ref{XREFset,,set}}
@end deftypefn


@node Multiple Plot Windows
@subsection Multiple Plot Windows
@cindex plotting, 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 figure scripts/plot/util/figure.m
@anchor{XREFfigure}
@deftypefn  {Command} {} figure
@deftypefnx {Command} {} figure @var{n}
@deftypefnx {Function File} {} figure (@var{n})
@deftypefnx {Function File} {} figure (@dots{}, "@var{property}", @var{value}, @dots{})
@deftypefnx {Function File} {@var{h} =} figure (@dots{})
Create a new figure window for plotting.

If no arguments are specified, a new figure with the next available number
is created.

If called with an integer @var{n}, and no such numbered figure exists, then
a new figure with the specified number is created.  If the figure already
exists then it is made visible and becomes the current figure for plotting.

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

The optional return value @var{h} is a graphics handle to the created figure
object.
@seealso{@ref{XREFaxes,,axes}, @ref{XREFgcf,,gcf}, @ref{XREFclf,,clf}, @ref{XREFclose,,close}}
@end deftypefn


@node Manipulation of Plot Windows
@subsection Manipulation of Plot Windows
@cindex plotting, window manipulation

By default, Octave refreshes the plot window when a prompt is printed,
or when waiting for input.  The
@code{drawnow} function is used to cause a plot window to be updated.

@c drawnow libinterp/corefcn/graphics.cc
@anchor{XREFdrawnow}
@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
@qcode{"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 refresh scripts/plot/util/refresh.m
@anchor{XREFrefresh}
@deftypefn  {Function File} {} refresh ()
@deftypefnx {Function File} {} refresh (@var{h})
Refresh a figure, forcing it to be redrawn.

When called without an argument the current figure is redrawn.  Otherwise,
the figure with graphic handle @var{h} is redrawn.
@seealso{@ref{XREFdrawnow,,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 newplot scripts/plot/util/newplot.m
@anchor{XREFnewplot}
@deftypefn  {Function File} {} newplot ()
@deftypefnx {Function File} {} newplot (@var{hfig})
@deftypefnx {Function File} {} newplot (@var{hax})
@deftypefnx {Function File} {@var{hax} =} newplot (@dots{})
Prepare graphics engine to produce a new plot.

This function is called at the beginning of all high-level plotting
functions.  It is not normally required in user programs.  @code{newplot}
queries the @qcode{"NextPlot"} field of the current figure and axis to
determine what to do.

@multitable @columnfractions .25 .75
@headitem Figure NextPlot @tab Action
@item @qcode{"new"} @tab Create a new figure and make it the current figure.

@item @qcode{"add"} (default) @tab Add new graphic objects to the current figure.

@item @qcode{"replacechildren"} @tab Delete child objects whose HandleVisibility is
set to @qcode{"on"}.  Set NextPlot property to @qcode{"add"}.  This
typically clears a figure, but leaves in place hidden objects such as
menubars.  This is equivalent to @code{clf}.

@item @qcode{"replace"} @tab Delete all child objects of the figure and
reset all figure properties to their defaults.  However, the following
four properties are not reset: Position, Units, PaperPosition, PaperUnits.
 This is equivalent to @code{clf reset}.
@end multitable

@multitable @columnfractions .25 .75
@headitem Axis NextPlot @tab Action
@item @qcode{"add"} @tab Add new graphic objects to the current axes.  This is
equivalent to @code{hold on}.

@item @qcode{"replacechildren"} @tab Delete child objects whose HandleVisibility is
set to @qcode{"on"}, but leave axis properties unmodified.  This typically
clears a plot, but preserves special settings such as log scaling for
axes.  This is equivalent to @code{cla}.

@item @qcode{"replace"} (default) @tab Delete all child objects of the
axis and reset all axis properties to their defaults.  However, the
following properties are not reset: Position, Units.  This is equivalent
to @code{cla reset}.
@end multitable

If the optional input @var{hfig} or @var{hax} is given then prepare the
specified figure or axes rather than the current figure and axes.

The optional return value @var{hax} is a graphics handle to the created
axes object (not figure).

@strong{Caution:} Calling @code{newplot} may change the current figure and
current axis.
@end deftypefn


@c hold scripts/plot/util/hold.m
@anchor{XREFhold}
@deftypefn  {Command} {} hold
@deftypefnx {Command} {} hold on
@deftypefnx {Command} {} hold off
@deftypefnx {Command} {} hold all
@deftypefnx {Function File} {} hold (@var{hax}, @dots{})
Toggle or set the @qcode{"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 all
Retain plot line color, line style, data, and settings so that subsequent
plot commands are displayed on a single graph with the next line color and
style.

@item hold off
Restore default graphics settings which clear the graph and reset axis
properties 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
for this axis rather than the current axes returned by @code{gca}.

To query the current hold state use the @code{ishold} function.
@seealso{@ref{XREFishold,,ishold}, @ref{XREFcla,,cla}, @ref{XREFclf,,clf}, @ref{XREFnewplot,,newplot}}
@end deftypefn


@c ishold scripts/plot/util/ishold.m
@anchor{XREFishold}
@deftypefn  {Command} {} ishold
@deftypefnx {Function File} {} ishold (@var{hax})
@deftypefnx {Function File} {} ishold (@var{hfig})
Return true if the next plot will be added to the current plot, or
false if the plot device will be cleared before drawing the next plot.

If the first argument is an axes handle @var{hax} or figure handle
@var{hfig} then operate on this plot rather than the current one.
@seealso{@ref{XREFhold,,hold}, @ref{XREFnewplot,,newplot}}
@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 clf scripts/plot/util/clf.m
@anchor{XREFclf}
@deftypefn  {Command} {} clf
@deftypefnx {Command} {} clf reset
@deftypefnx {Function File} {} clf (@var{hfig})
@deftypefnx {Function File} {} clf (@var{hfig}, "reset")
@deftypefnx {Function File} {@var{h} =} clf (@dots{})
Clear the current figure window.

@code{clf} operates by deleting child graphics objects with visible
handles (HandleVisibility = @qcode{"on"}).

If the optional argument @qcode{"reset"} is specified, delete all child
objects including those with hidden handles and reset all figure
properties to their defaults.  However, the following properties are not
reset: Position, Units, PaperPosition, PaperUnits.

If the first argument @var{hfig} is a figure handle, then operate on
this figure rather than the current figure returned by @code{gcf}.

The optional return value @var{h} is the graphics handle of the figure
window that was cleared.
@seealso{@ref{XREFcla,,cla}, @ref{XREFclose,,close}, @ref{XREFdelete,,delete}, @ref{XREFreset,,reset}}
@end deftypefn


@c cla scripts/plot/util/cla.m
@anchor{XREFcla}
@deftypefn  {Command} {} cla
@deftypefnx {Command} {} cla reset
@deftypefnx {Function File} {} cla (@var{hax})
@deftypefnx {Function File} {} cla (@var{hax}, "reset")
Clear the current axes.

@code{cla} operates by deleting child graphic objects with visible
handles (HandleVisibility = @qcode{"on"}).

If the optional argument @qcode{"reset"} is specified, delete all child
objects including those with hidden handles and reset all axis properties
to their defaults.  However, the following properties are not reset:
Position, Units.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.
@seealso{@ref{XREFclf,,clf}, @ref{XREFdelete,,delete}, @ref{XREFreset,,reset}}
@end deftypefn


@c shg scripts/plot/util/shg.m
@anchor{XREFshg}
@deftypefn {Command} {} shg
Show the graph window.

Currently, this is the same as executing @code{drawnow}.
@seealso{@ref{XREFdrawnow,,drawnow}, @ref{XREFfigure,,figure}}
@end deftypefn


@c delete scripts/miscellaneous/delete.m
@anchor{XREFdelete}
@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{XREFclf,,clf}, @ref{XREFcla,,cla}, @ref{XREFunlink,,unlink}}
@end deftypefn


@c close scripts/plot/util/close.m
@anchor{XREFclose}
@deftypefn  {Command} {} close
@deftypefnx {Command} {} close (@var{h})
@deftypefnx {Command} {} close all
@deftypefnx {Command} {} close all hidden
Close figure window(s).

When called with no arguments, close the current figure.  This is equivalent
to @code{close (gcf)}.  If the input @var{h} is a graphic handle, or vector
of graphics handles, then close each figure in @var{h}.

If the argument @qcode{"all"} is given then all figures with visible handles
(HandleVisibility = @qcode{"on"}) are closed.

If the argument @qcode{"all hidden"} is given then all figures, including
hidden ones, are closed.

Implementation Note: @code{close} operates by calling the function specified
by the @qcode{"closerequestfcn"} property for each figure.  By default, the
function @code{closereq} is used.  It is possible that the function invoked
will delay or abort removing the figure.  To remove a figure without
executing any callback functions use @code{delete}.  When writing a callback
function to close a window do not use @code{close} to avoid recursion.

@seealso{@ref{XREFclosereq,,closereq}, @ref{XREFdelete,,delete}}
@end deftypefn


@c closereq scripts/plot/util/closereq.m
@anchor{XREFclosereq}
@deftypefn {Function File} {} closereq ()
Close the current figure and delete all graphics objects associated with it.

By default, the @qcode{"closerequestfcn"} property of a new plot figure
points to this function.
@seealso{@ref{XREFclose,,close}, @ref{XREFdelete,,delete}}
@end deftypefn


@node Use of the @code{interpreter} Property
@subsection Use of the @code{interpreter} Property

All text objects---such as titles, labels, legends, and text---include
the property @qcode{"interpreter"}, this property determines the manner in
which special control sequences in the text are rendered.  If the interpreter
is set to @qcode{"none"}, then no rendering occurs.  Currently the
@qcode{"latex"} interpreter is not implemented and is equivalent to
@qcode{"none"}.

The @qcode{"tex"} option implements a subset of @TeX{} functionality when
rendering text.  This allows the insertion of special glyphs such as Greek
characters or mathematical symbols.  The special characters are inserted with
a code following a backslash (\) character, as in the table
@ref{tab:extended}.

In addition, the formatting of the text can be changed within the string
by using 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 may 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

@noindent
where the character @qcode{'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, superscripting and subscripting can be controlled with the @qcode{'^'}
and @qcode{'_'} characters.  If the @qcode{'^'} or @qcode{'_'} 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 @qcode{'^'} or @qcode{'_'} is super- or sub-scripted.

@float Table,tab:extended
@tex
\vskip 6pt
\newdimen\cola \cola=78pt
\newdimen\colb \colb=78pt
\newdimen\colc \colc=78pt
\def\symtable#1#2#3{
\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt
\hskip36pt #1
\vskip6pt
\halign{
\vrule height2.0ex depth1.ex width 0.6pt #2\tabskip=0.3em &
#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule &
#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule &
#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule
width 0.6pt \tabskip=0pt\cr
\noalign{\hrule height 0.6pt}
& Code && Sym && Code && Sym && Code && Sym &\cr
\noalign{\hrule}
#3
\noalign{\hrule height 0.6pt}
}
}\hfill}}
\hoffset72pt
\symtable{Greek Lowercase Letters} {#}
{& \hbox to \cola{$\backslash$alpha }    && $\alpha$
&& \hbox to \colb{$\backslash$beta }     && $\beta$
&& \hbox to \colc{$\backslash$gamma}     && $\gamma$     &\cr
& $\backslash$delta      && $\delta$
&& $\backslash$epsilon   && $\epsilon$
&& $\backslash$zeta      && $\zeta$      &\cr
& $\backslash$eta        && $\eta$
&& $\backslash$theta     && $\theta$
&& $\backslash$vartheta  && $\vartheta$  &\cr
& $\backslash$iota       && $\iota$
&& $\backslash$kappa     && $\kappa$
&& $\backslash$lambda    && $\lambda$    &\cr
& $\backslash$mu         && $\mu$
&& $\backslash$nu        && $\nu$
&& $\backslash$xi        && $\xi$        &\cr
& $\backslash$o          && $o$
&& $\backslash$pi        && $\pi$
&& $\backslash$varpi     && $\varpi$     &\cr
& $\backslash$rho        && $\rho$
&& $\backslash$sigma     && $\sigma$
&& $\backslash$varsigma  && $\varsigma$  &\cr
& $\backslash$tau        && $\tau$
&& $\backslash$upsilon   && $\upsilon$
&& $\backslash$phi       && $\phi$       &\cr
& $\backslash$chi        && $\chi$
&& $\backslash$psi       && $\psi$
&& $\backslash$omega     && $\omega$     &\cr}
\vskip12pt
\symtable{Greek Uppercase Letters} {#}
{& \hbox to \cola{$\backslash$Gamma}   && $\Gamma$
&& \hbox to \colb{$\backslash$Delta}   && $\Delta$
&& \hbox to \colc{$\backslash$Theta}   && $\Theta$      &\cr
& $\backslash$Lambda   && $\Lambda$
&& $\backslash$Xi      && $\Xi$
&& $\backslash$Pi      && $\Pi$         &\cr
& $\backslash$Sigma    && $\Sigma$
&& $\backslash$Upsilon && $\Upsilon$
&& $\backslash$Phi     && $\Phi$        &\cr
& $\backslash$Psi      && $\Psi$
&& $\backslash$Omega   && $\Omega$
&&    &&       &\cr}
\vskip12pt
\symtable{Misc Symbols Type Ord} {#}
{& \hbox to \cola{$\backslash$aleph}       && $\aleph$
&& \hbox to \colb{$\backslash$wp}          && $\wp$
&& \hbox to \colc{$\backslash$Re}          && $\Re$      &\cr
& $\backslash$Im           && $\Im$
&& $\backslash$partial     && $\partial$
&& $\backslash$infty       && $\infty$       &\cr
& $\backslash$prime        && $\prime$
&& $\backslash$nabla       && $\nabla$
&& $\backslash$surd        && $\surd$        &\cr
& $\backslash$angle        && $\angle$
&& $\backslash$forall      && $\forall$
&& $\backslash$exists      && $\exists$      &\cr
& $\backslash$neg          && $\neg$
&& $\backslash$clubsuit    && $\clubsuit$
&& $\backslash$diamondsuit && $\diamondsuit$ &\cr
& $\backslash$heartsuit    && $\heartsuit$
&& $\backslash$spadesuit   && $\spadesuit$
&&    &&       &\cr}
\vskip12pt
\symtable{``Large'' Operators} {#}
{& \hbox to \cola{$\backslash$int}   && $\int$
&& \hbox to \colb{}   &&
&& \hbox to \colc{}   &&       &\cr}
\vskip12pt
\symtable{Binary operators} {#}
{& \hbox to \cola{$\backslash$pm}     && $\pm$
&& \hbox to \colb{$\backslash$cdot}   && $\cdot$
&& \hbox to \colc{$\backslash$times}  && $\times$      &\cr
& $\backslash$ast     && $\ast$
&& $\backslash$circ   && $\circ$
&& $\backslash$bullet && $\bullet$     &\cr
& $\backslash$div     && $\div$
&& $\backslash$cap    && $\cap$
&& $\backslash$cup    && $\cup$        &\cr
& $\backslash$vee     && $\vee$
&& $\backslash$wedge  && $\wedge$
&& $\backslash$oplus  && $\oplus$      &\cr
& $\backslash$otimes  && $\otimes$
&& $\backslash$oslash && $\oslash$
&&    &&      &\cr}
@end tex
@ifnottex
@multitable @columnfractions .25 .25 .25 .25
@item Greek Lowercase Letters
@item @tab  \alpha      @tab  \beta        @tab  \gamma
@item @tab  \delta      @tab  \epsilon     @tab  \zeta
@item @tab  \eta        @tab  \theta       @tab  \vartheta
@item @tab  \iota       @tab  \kappa       @tab  \lambda
@item @tab  \mu         @tab  \nu          @tab  \xi
@item @tab  \o          @tab  \pi          @tab  \varpi
@item @tab  \rho        @tab  \sigma       @tab  \varsigma
@item @tab  \tau        @tab  \upsilon     @tab  \phi
@item @tab  \chi        @tab  \psi         @tab  \omega
@item Greek Uppercase Letters
@item @tab  \Gamma      @tab  \Delta       @tab  \Theta
@item @tab  \Lambda     @tab  \Xi          @tab  \Pi
@item @tab  \Sigma      @tab  \Upsilon     @tab  \Phi
@item @tab  \Psi        @tab  \Omega       @tab
@item Misc Symbols Type Ord
@item @tab  \aleph      @tab  \wp          @tab  \Re
@item @tab  \Im         @tab  \partial     @tab  \infty
@item @tab  \prime      @tab  \nabla       @tab  \surd
@item @tab  \angle      @tab  \forall      @tab  \exists
@item @tab  \neg        @tab  \clubsuit    @tab  \diamondsuit
@item @tab  \heartsuit  @tab  \spadesuit   @tab
@item ``Large'' Operators
@item @tab  \int
@item Binary Operators
@item @tab  \pm         @tab  \cdot        @tab  \times
@item @tab  \ast        @tab  \circ        @tab  \bullet
@item @tab  \div        @tab  \cap         @tab  \cup
@item @tab  \vee        @tab  \wedge       @tab  \oplus
@item @tab  \otimes     @tab  \oslash      @tab
@item Relations
@item @tab  \leq        @tab  \subset      @tab  \subseteq
@item @tab  \in         @tab  \geq         @tab  \supset
@item @tab  \supseteq   @tab  \ni          @tab  \mid
@item @tab  \equiv      @tab  \sim         @tab  \approx
@item @tab  \cong       @tab  \propto      @tab  \perp
@item Arrows
@item @tab  \leftarrow  @tab  \Leftarrow   @tab  \rightarrow
@item @tab  \Rightarrow @tab  \leftrightarrow @tab  \uparrow
@item @tab  \downarrow  @tab               @tab
@item Openings and Closings
@item @tab  \lfloor     @tab  \langle      @tab  \lceil
@item @tab  \rfloor     @tab  \rangle      @tab  \rceil
@item Alternate Names
@item @tab  \neq
@item Other
@item @tab  \ldots      @tab  \0          @tab  \copyright
@item @tab  \deg
@end multitable
@end ifnottex
@caption{Available special characters in @TeX{} mode}
@end float
@float
@tex
\vskip 6pt
\newdimen\cola \cola=78pt
\newdimen\colb \colb=78pt
\newdimen\colc \colc=78pt
\def\symtable#1#2#3{\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt
\hskip36pt #1
\vskip6pt
\halign{
\vrule height2.0ex depth1.ex width 0.6pt #2\tabskip=0.3em &
#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule &
#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule &
#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule
width 0.6pt \tabskip=0pt\cr
\noalign{\hrule height 0.6pt}
& Code && Sym && Code && Sym && Code && Sym &\cr
\noalign{\hrule}
#3
\noalign{\hrule height 0.6pt}
}
}\hfill}}
\hoffset72pt
\vskip12pt
\symtable{Relations} {#}
{& \hbox to \cola{$\backslash$leq}      && $\leq$
&& \hbox to \colb{$\backslash$subset}   && $\subset$
&& \hbox to \colc{$\backslash$subseteq} && $\subseteq$    &\cr
& $\backslash$in        && $\in$
&& $\backslash$geq      && $\geq$
&& $\backslash$supset   && $\supset$      &\cr
& $\backslash$supseteq  && $\supseteq$
&& $\backslash$ni       && $\ni$
&& $\backslash$mid      && $\mid$         &\cr
& $\backslash$equiv     && $\equiv$
&& $\backslash$sim      && $\sim$
&& $\backslash$approx   && $\approx$      &\cr
& $\backslash$cong      && $\cong$
&& $\backslash$propto   && $\propto$
&& $\backslash$perp     && $\perp$        &\cr}
\vskip12pt
\symtable{Arrows} {#}
{& \hbox to \cola{$\backslash$leftarrow}      && $\leftarrow$
&& \hbox to \colb{$\backslash$Leftarrow}      && $\Leftarrow$
&& \hbox to \colc{$\backslash$rightarrow}     && $\rightarrow$      &\cr
& $\backslash$Rightarrow      && $\Rightarrow$
&& $\backslash$leftrightarrow && $\leftrightarrow$
&& $\backslash$uparrow        && $\uparrow$         &\cr
& $\backslash$downarrow       && $\downarrow$
&&   && 
&&   &&       &\cr}
\vskip12pt
\symtable{Openings and Closings} {#}
{& \hbox to \cola{$\backslash$lfloor   }    && $\lfloor$
&& \hbox to \colb{$\backslash$langle   }    && $\langle$
&& \hbox to \colc{$\backslash$lceil    }    && $\lceil$      &\cr
& $\backslash$rfloor    && $\rfloor$
&& $\backslash$rangle   && $\rangle$
&& $\backslash$rceil    && $\rceil$      &\cr}
\vskip12pt
\symtable{Alternate Names} {#}
{& \hbox to \cola{$\backslash$neq}   && $\neq$
&& \hbox to \colb{}   && 
&& \hbox to \colc{}   &&   &\cr}
\vskip12pt
\symtable{Other (not in Appendix F Tables)} {#}
{& \hbox to \cola{$\backslash$ldots}     && $\ldots$
&& \hbox to \colb{$\backslash$0}         && $\oslash$
&& \hbox to \colc{$\backslash$copyright} && $\copyright$      &\cr
& $\backslash$deg        && $^\circ$
&&    &&  
&&    &&       &\cr}
\vskip12pt
\hskip36pt Table 15.1: Available special characters in \TeX\ mode (cont.)
@end tex
@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 @TeX{} interpreter}
@end float
@end ifnotinfo

@node Printing and Saving Plots
@subsection Printing and Saving Plots
@cindex plotting, saving and printing plots
@cindex printing plots
@cindex saving plots

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

@example
print -dpsc
@end example

@noindent
prints the current figure to a color PostScript printer.  And,

@example
print -deps foo.eps
@end example

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

@c print scripts/plot/util/print.m
@anchor{XREFprint}
@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 plot, or save it to a file.

Both output formatted for printing (PDF and PostScript), and many bitmapped
and vector image formats are supported.

@var{filename} defines the name of the output file.  If the
file name has no suffix, one is inferred from the specified
device and appended to the file name.  If no filename is
specified, the output is sent to the printer.

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

For output to a printer, PostScript file, or PDF file,
the paper size is specified by the figure's @code{papersize}
property.  The location and size of the image on the page are
specified by the figure's @code{paperposition} property.  The
orientation of the page is specified by the figure's
@code{paperorientation} property.

The width and height of images are specified by the figure's
@code{paperpositon(3:4)} property values.

The @code{print} command supports many @var{options}:

@table @code
@item -f@var{h}
  Specify the handle, @var{h}, of the figure to be printed.  The
default is the current figure.

@item -P@var{printer}
  Set the @var{printer} name to which the plot 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 @qcode{"gs"} and @qcode{"gswin32c"}, respectively.

@item  -color
@itemx -mono
  Color or monochrome output.

@item  -solid
@itemx -dashed
  Force all lines to be solid or dashed, respectively.

@item  -portrait
@itemx -landscape
  Specify the orientation of the plot for printed output.  For
non-printed output the aspect ratio of the output corresponds to
the plot area defined by the @qcode{"paperposition"} property in the
orientation specified.  This option is equivalent to changing
the figure's @qcode{"paperorientation"} property.

@item  -TextAlphaBits=@var{n}
@itemx -GraphicsAlphaBits=@var{n}
  Octave is able to produce output for various printers, bitmaps, and
vector formats by using Ghostscript.
For bitmap and printer output anti-aliasing is applied using
Ghostscript's TextAlphaBits and GraphicsAlphaBits options.
The default number of bits for each is 4.
Allowed values for @var{N} are 1, 2, or 4.

@item -d@var{device}
  The available output format is specified by the option @var{device},
and is one of:

@table @code
@item  ps
@itemx ps2
@itemx psc
@itemx psc2
    PostScript (level 1 and 2, mono and color).  The FLTK graphics
toolkit generates PostScript level 3.0.

@item  eps
@itemx eps2
@itemx epsc
@itemx epsc2
    Encapsulated PostScript (level 1 and 2, mono and color).  The FLTK
graphic toolkit generates PostScript level 3.0.

@item  tex
@itemx epslatex
@itemx epslatexstandalone
@itemx pstex
@itemx pslatex
@itemx pdflatex
    Generate a @LaTeX{} (or @TeX{}) file for labels and eps/ps/pdf
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.  The @code{pdflatex} device
is only available for the FLTK graphics toolkit.

@item tikz
    Generate a @LaTeX{} file using PGF/TikZ@.  For the FLTK toolkit
the result is PGF.

@item  ill
@itemx aifm
    Adobe Illustrator (Obsolete for Gnuplot versions > 4.2)

@item  cdr
@itemx @nospell{corel}
    CorelDraw

@item dxf
    AutoCAD

@item  emf
@itemx meta
    Microsoft Enhanced Metafile

@item fig
    XFig.  For the Gnuplot graphics toolkit, the additional options
@option{-textspecial} or @option{-textnormal} can be used to control
whether the special flag should be set for the text in
the figure.  (default is @option{-textnormal})

@item hpgl
    HP plotter language

@item mf
    Metafont

@item png
    Portable network graphics

@item  jpg
@itemx jpeg
    JPEG image

@item gif
    GIF image (only available for the Gnuplot graphics toolkit)

@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{ghostscript_device}
  Additional devices are supported by Ghostscript.
Some examples are;

@table @code
@item ljet2p
    HP LaserJet @nospell{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

@item pdfwrite
    Produces pdf output from eps
@end table

  For a complete list, type @code{system ("gs -h")} to see what formats
and devices are available.

  When Ghostscript output is sent to a printer the size is determined
by the figure's @qcode{"papersize"} property.  When the output
is sent to a file the size is determined by the plot box defined by
the figure's @qcode{"paperposition"} property.

@item -append
  Append PostScript or PDF output to a pre-existing file of the same type.

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

@item  -loose
@itemx -tight
  Force a tight or loose bounding box for eps files.  The default is loose.

@item -@var{preview}
  Add a preview to eps files.  Supported formats are:

@table @code
@item -interchange
    Provide an interchange preview.

@item -metalfile
    Provide a metafile preview.

@item -pict
    Provide pict preview.

@item -tiff
    Provide a tiff preview.
@end table

@item -S@var{xsize},@var{ysize}
  Plot size in pixels for EMF, GIF, JPEG, PBM, PNG, and SVG@.  For
PS, EPS, PDF, and other vector formats the plot size is in points.
This option is equivalent to changing the size of the plot box
associated with the @qcode{"paperposition"} property.  When using the
command form of the print function you must quote the
@var{xsize},@var{ysize} option.  For example, by writing @w{"-S640,480"}.

@item  -F@var{fontname}
@itemx -F@var{fontname}:@var{size}
@itemx -F:@var{size}
  Use @var{fontname} and/or @var{fontsize} for all text.
@var{fontname} is ignored for some devices: dxf, fig, hpgl, etc.
@end table

The filename and options can be given in any order.

Example: Print to a file using the svg device.

@example
@group
figure (1);
clf ();
surf (peaks);
print -dsvg figure1.svg
@end group
@end example

Example: Print to an HP DeskJet 550C.

@example
@group
clf ();
surf (peaks);
print -dcdj550
@end group
@end example

@seealso{@ref{XREFsaveas,,saveas}, @ref{XREForient,,orient}, @ref{XREFfigure,,figure}}
@end deftypefn


@c saveas scripts/plot/util/saveas.m
@anchor{XREFsaveas}
@deftypefn  {Function File} {} saveas (@var{h}, @var{filename})
@deftypefnx {Function File} {} saveas (@var{h}, @var{filename}, @var{fmt})
Save graphic object @var{h} to the file @var{filename} in graphic
format @var{fmt}.

@var{fmt} should be one of the following formats:

@table @code
@item ps
    PostScript

@item eps
    Encapsulated PostScript

@item jpg
    JPEG Image

@item png
    PNG Image

@item emf
    Enhanced Meta File

@item pdf
    Portable Document Format
@end table

All device formats specified in @code{print} may also be used.  If
@var{fmt} is omitted it is extracted from the extension of @var{filename}.
The default format is @qcode{"pdf"}.

@example
@group
clf ();
surf (peaks);
saveas (1, "figure1.png");
@end group
@end example

@seealso{@ref{XREFprint,,print}, @ref{XREForient,,orient}}
@end deftypefn


@c orient scripts/plot/appearance/orient.m
@anchor{XREForient}
@deftypefn  {Function File} {} orient (@var{orientation})
@deftypefnx {Function File} {} orient (@var{hfig}, @var{orientation})
@deftypefnx {Function File} {@var{orientation} =} orient ()
@deftypefnx {Function File} {@var{orientation} =} orient (@var{hfig})
Query or set the print orientation for figure @var{hfig}.

Valid values for @var{orientation} are @qcode{"portrait"},
@qcode{"landscape"}, and @qcode{"tall"}.

The @qcode{"landscape"} option changes the orientation so the plot width
is larger than the plot height.  The @qcode{"paperposition"} is also
modified so that the plot fills the page, while leaving a 0.25 inch border.

The @qcode{"tall"} option sets the orientation to @qcode{"portrait"} and
fills the page with the plot, while leaving a 0.25 inch border.

The @qcode{"portrait"} option (default) changes the orientation so the plot
height is larger than the plot width.  It also restores the default
@qcode{"paperposition"} property.

When called with no arguments, return the current print orientation.

If the argument @var{hfig} is omitted, then operate on the current figure
returned by @code{gcf}.
@seealso{@ref{XREFprint,,print}, @ref{XREFsaveas,,saveas}}
@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.  Menus may also be created
and populated with specific user commands via the @code{uimenu} function.

@c ginput scripts/plot/util/ginput.m
@anchor{XREFginput}
@deftypefn  {Function File} {[@var{x}, @var{y}, @var{buttons}] =} ginput (@var{n})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{buttons}] =} ginput ()
Return the position and type of mouse button clicks and/or key strokes
in the current figure window.

If @var{n} is defined, then capture @var{n} events before returning.
When @var{n} is not defined @code{ginput} will loop until the return key
@key{RET} is pressed.

The return values @var{x}, @var{y} are the coordinates where the mouse
was clicked in the units of the current axes.  The return value @var{button}
is 1, 2, or 3 for the left, middle, or right button.  If a key is pressed
the ASCII value is returned in @var{button}.
@seealso{@ref{XREFgtext,,gtext}, @ref{XREFwaitforbuttonpress,,waitforbuttonpress}}
@end deftypefn


@c waitforbuttonpress scripts/gui/waitforbuttonpress.m
@anchor{XREFwaitforbuttonpress}
@deftypefn  {Function File} {} waitforbuttonpress ()
@deftypefnx {Function File} {@var{b} =} waitforbuttonpress ()
Wait for mouse click or key press over the current figure window.

The return value of @var{b} is 0 if a mouse button was pressed or 1 if a
key was pressed.
@seealso{@ref{XREFwaitfor,,waitfor}, @ref{XREFginput,,ginput}, @ref{XREFkbhit,,kbhit}}
@end deftypefn


@c gtext scripts/plot/appearance/gtext.m
@anchor{XREFgtext}
@deftypefn  {Function File} {} gtext (@var{s})
@deftypefnx {Function File} {} gtext (@{@var{s1}, @var{s2}, @dots{}@})
@deftypefnx {Function File} {} gtext (@{@var{s1}; @var{s2}; @dots{}@})
@deftypefnx {Function File} {} gtext (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} gtext (@dots{})
Place text on the current figure using the mouse.

The text is defined by the string @var{s}.  If @var{s} is a cell string
organized as a row vector then each string of the cell array is written to a
separate line.  If @var{s} is organized as a column vector then one string
element of the cell array is placed for every mouse click.

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

The optional return value @var{h} is a graphics handle to the created
text object(s).
@seealso{@ref{XREFginput,,ginput}, @ref{XREFtext,,text}}
@end deftypefn


@c uimenu scripts/gui/uimenu.m
@anchor{XREFuimenu}
@deftypefn  {Function File} {} uimenu (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} uimenu (@var{h}, @var{property}, @var{value}, @dots{})
Create a uimenu object and return a handle to it.  If @var{h} is omitted
then a top-level menu for the current figure is created.  If @var{h}
is given then a submenu relative to @var{h} is created.

uimenu objects have the following specific properties:

@table @asis
@item @qcode{"accelerator"}
A string containing the key combination together with CTRL to execute this
menu entry (e.g., @qcode{"x"} for CTRL+x).

@item @qcode{"callback"}
Is the function called when this menu entry is executed.  It can be either a
function string (e.g., @qcode{"myfun"}), a function handle (e.g., @@myfun)
or a cell array containing the function handle and arguments for the
callback function (e.g., @{@@myfun, arg1, arg2@}).

@item @qcode{"checked"}
Can be set @qcode{"on"} or @qcode{"off"}.  Sets a mark at this menu entry.

@item @qcode{"enable"}
Can be set @qcode{"on"} or @qcode{"off"}.  If disabled the menu entry
cannot be selected and it is grayed out.

@item @qcode{"foregroundcolor"}
A color value setting the text color for this menu entry.

@item @qcode{"label"}
A string containing the label for this menu entry.  A @qcode{"&"}-symbol
can be used to mark the @qcode{"accelerator"} character (e.g.,
@nospell{@qcode{"E&xit"}})

@item @qcode{"position"}
An scalar value containing the relative menu position.  The entry with the
lowest value is at the first position starting from left or top.

@item @qcode{"separator"}
Can be set @qcode{"on"} or @qcode{"off"}.  If enabled it draws a separator
line above the current position.  It is ignored for top level entries.

@end table

Examples:

@example
@group
f = uimenu ("label", "&File", "accelerator", "f");
e = uimenu ("label", "&Edit", "accelerator", "e");
uimenu (f, "label", "Close", "accelerator", "q", ...
           "callback", "close (gcf)");
uimenu (e, "label", "Toggle &Grid", "accelerator", "g", ...
           "callback", "grid (gca)");
@end group
@end example
@seealso{@ref{XREFfigure,,figure}}
@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 sombrero scripts/plot/draw/sombrero.m
@anchor{XREFsombrero}
@deftypefn  {Function File} {} sombrero ()
@deftypefnx {Function File} {} sombrero (@var{n})
@deftypefnx {Function File} {@var{z} =} sombrero (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} sombrero (@dots{})
Plot the familiar 3-D sombrero function.

The function plotted is
@tex
$$z = { \rm{sin} (\sqrt {(x^2 + y^2)}) \over \sqrt {(x^2 + y^2)} }$$
@end tex
@ifnottex

@example
z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2))
@end example

@end ifnottex
Called without a return argument, @code{sombrero} plots the surface of the
above function over the meshgrid [-8,8] using @code{surf}.

If @var{n} is a scalar the plot is made with @var{n} grid lines.
The default value for @var{n} is 41.

When called with output arguments, return the data for the function
evaluated over the meshgrid.  This can subsequently be plotted with
@code{surf (@var{x}, @var{y}, @var{z})}.

@seealso{@ref{XREFpeaks,,peaks}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFmesh,,mesh}, @ref{XREFsurf,,surf}}
@end deftypefn


@c peaks scripts/plot/draw/peaks.m
@anchor{XREFpeaks}
@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{})
Plot 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{surf}.

If @var{n} is a scalar, @code{peaks} plots the value of the above
function on an @var{n}-by-@var{n} mesh over the range [-3,3].  The
default value for @var{n} is 49.

If @var{n} is a vector, then it represents the grid values over which
to calculate the function.  If @var{x} and @var{y} are specified then
the function value is calculated over the specified grid of vertices.

When called with output arguments, return the data for the function
evaluated over the meshgrid.  This can subsequently be plotted with
@code{surf (@var{x}, @var{y}, @var{z})}.

@seealso{@ref{XREFsombrero,,sombrero}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFmesh,,mesh}, @ref{XREFsurf,,surf}}
@end deftypefn

@node Graphics Data Structures
@section Graphics Data Structures
@cindex graphics data structures

@menu
* Introduction to Graphics Structures::
* Graphics Objects::
* Graphics Object Properties::
* Searching Properties::
* Managing Default Properties::
@end menu

@node Introduction to Graphics Structures
@subsection Introduction to Graphics Structures
@cindex introduction to graphics structures
@anchor{XREFgraphics structures}

The graphics functions use pointers, which are of class graphics_handle, in
order to address the data structures which control graphical displays.  A
graphics handle may point any one of a number of different object types.  The
objects are the graphics data structures.  The types of objects are:
@code{figure}, @code{axes}, @code{line}, @code{text}, @code{patch},
@code{surface}, @code{text} and @code{image}.

Each of these objects has a function by the same name. and, each of these
functions returns a graphics handle pointing to an object of corresponding
type.  In addition there are several functions which operate on properties of
the graphics objects and which return handles: the functions @code{ plot} and
@code{plot3} return a handle pointing to an object of type line, the function
@code{subplot} returns a handle pointing to an object of type axes, the
function @code{fill} returns a handle pointing to an object of type patch, the
functions @code{area}, @code{bar}, @code{barh}, @code{contour},
@code{contourf}, @code{contour3}, @code{surf}, @code{mesh}, @code{surfc},
@code{meshc}, @code{errorbar}, @code{quiver}, @code{quiver3}, @code{scatter},
@code{scatter3}, @code{stair}, @code{stem}, @code{stem3} each return a handle
as documented in @ref{XREFdatasources,,Data Sources}.


The graphics objects are arranged in a hierarchy:

1. The root is at 0.  i.e., @code{get (0)} returns the properties of the root
   object.

2. Below the root are @code{figure} objects.

3. Below the @code{figure} objects are @code{axes}.

4. Below the @code{axes} objects are
@code{line}, @code{text}, @code{patch},
@code{surface}, and @code{image} objects.

Graphics handles may be distinguished from function handles
(@pxref{Function Handles}) by means of the function @code{ishandle}.
@code{ishandle} returns true if its argument is a handle of a graphics object.
In addition, the figure object may be tested using @code{isfigure}.
@code{isfigure} returns true only if its argument is a handle of a figure.  The
@code{whos} function can be used to show the object type of each currently
defined graphics handle.  (Note: this is not true today, but it is, I hope,
considered an error in whos.  It may be better to have whos just show
graphics_handle as the class, and provide a new function which, given a
graphics handle, returns its object type.  This could generalize the ishandle()
functions and, in fact, replace them.)

The @code{get} and @code{set} commands are used to obtain and set the values of
properties of graphics objects.  In addition, the @code{get} command may be
used to obtain property names.

For example, the property @qcode{"type"} of the graphics object pointed to by
the graphics handle h may be displayed by:

@example
get (h, "type")
@end example

The properties and their current values are returned by @code{get (h)}
where h is a handle of a graphics object.  If only the names of the
allowed properties are wanted they may be displayed by:
@code{get (h, "")}.

Thus, for example:

@smallexample
h = figure ();
get (h, "type")
ans = figure
get (h, "");
error: get: ambiguous figure property name ; possible matches:

__enhanced__           hittest                resize
__graphics_toolkit__   integerhandle          resizefcn
__guidata__            interruptible          selected
__modified__           inverthardcopy         selectionhighlight
__myhandle__           keypressfcn            selectiontype
__plot_stream__        keyreleasefcn          tag
alphamap               menubar                toolbar
beingdeleted           mincolormap            type
busyaction             name                   uicontextmenu
buttondownfcn          nextplot               units
children               numbertitle            userdata
clipping               outerposition          visible
closerequestfcn        paperorientation       windowbuttondownfcn
color                  paperposition          windowbuttonmotionfcn
colormap               paperpositionmode      windowbuttonupfcn
createfcn              papersize              windowkeypressfcn
currentaxes            papertype              windowkeyreleasefcn
currentcharacter       paperunits             windowscrollwheelfcn
currentobject          parent                 windowstyle
currentpoint           pointer                wvisual
deletefcn              pointershapecdata      wvisualmode
dockcontrols           pointershapehotspot    xdisplay
doublebuffer           position               xvisual
filename               renderer               xvisualmode
handlevisibility       renderermode
@end smallexample

The root figure has index 0.  Its properties may be displayed by:
@code{get (0, "")}.

The uses of @code{get} and @code{set} are further explained in
@ref{XREFget,,get}, @ref{XREFset,,set}.

@c isprop scripts/plot/util/isprop.m
@anchor{XREFisprop}
@deftypefn {Function File} {@var{res} =} isprop (@var{h}, "@var{prop}")
Return true if @var{prop} is a property of the object with handle @var{h}.

@var{h} may also be an array of handles in which case @var{res} will be a
logical array indicating whether each handle has the property @var{prop}.
@seealso{@ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFismethod,,ismethod}, @ref{XREFisobject,,isobject}}
@end deftypefn


@node Graphics Objects
@subsection Graphics Objects
@cindex graphics objects

The hierarchy of graphics objects was explained above.
@xref{Introduction to Graphics Structures}.  Here the
specific objects are described, and the properties contained in
these objects are discussed.  Keep in mind that
graphics objects are always referenced by @dfn{handle}.

@table @asis
@c @group

@item root figure
@cindex root figure graphics object
@cindex graphics object, root figure
the top level of the hierarchy and the parent of all figure objects.
The handle index of the root figure is 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.
@c @end group
@end table

@subsubsection Creating Graphics Objects
@cindex creating graphics objects

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

@c axes scripts/plot/util/axes.m
@anchor{XREFaxes}
@deftypefn  {Function File} {} axes ()
@deftypefnx {Function File} {} axes (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} axes (@var{hax})
@deftypefnx {Function File} {@var{h} =} axes (@dots{})
Create an axes object and return a handle to it, or set the current
axes to @var{hax}.

Called without any arguments, or with @var{property}/@var{value} pairs,
construct a new axes.  For accepted properties and corresponding
values, @pxref{XREFset,,set}.

Called with a single axes handle argument @var{hax}, the function makes
@var{hax} the current axis.  It also restacks the axes in the
corresponding figure so that @var{hax} is the first entry in the list
of children.  This causes @var{hax} to be displayed on top of any other
axes objects (Z-order stacking).

@seealso {gca, set, get}
@end deftypefn


@c line scripts/plot/draw/line.m
@anchor{XREFline}
@deftypefn  {Function File} {} line ()
@deftypefnx {Function File} {} line (@var{x}, @var{y})
@deftypefnx {Function File} {} line (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@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{})
@deftypefnx {Function File} {} line (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} line (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} line (@dots{})
Create line object from @var{x} and @var{y} (and possibly @var{z}) and
insert in the current axes.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

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

@seealso{@ref{XREFimage,,image}, @ref{XREFpatch,,patch}, @ref{XREFrectangle,,rectangle}, @ref{XREFsurface,,surface}, @ref{XREFtext,,text}}
@end deftypefn


@c patch scripts/plot/draw/patch.m
@anchor{XREFpatch}
@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{faces}, "Vertices", @var{verts}, @dots{})
@deftypefnx {Function File} {} patch (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} patch (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} patch (@dots{})
Create patch object in the current axes with vertices at locations
(@var{x}, @var{y}) and of color @var{c}.

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

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

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

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

A third input form is to create a structure @var{fv} with the fields
@qcode{"vertices"}, @qcode{"faces"}, and optionally
@qcode{"facevertexcdata"}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

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

Implementation Note: Patches are highly configurable objects.  To truly
customize them requires setting patch properties directly.  Useful patch
properties are: @qcode{"cdata"}, @qcode{"edgecolor"},
@qcode{"facecolor"}, @qcode{"faces"}, @qcode{"facevertexcdata"}.
@seealso{@ref{XREFfill,,fill}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c fill scripts/plot/draw/fill.m
@anchor{XREFfill}
@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{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} fill (@dots{})
Create one or more filled 2-D polygons.

The inputs @var{x} and @var{y} are the coordinates of the polygon vertices.
If the inputs are matrices then the rows represent different vertices and
each column produces a different polygon.  @code{fill} will close any open
polygons before plotting. 

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

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the created patch objects.

Example: red square

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

@seealso{@ref{XREFpatch,,patch}, @ref{XREFcaxis,,caxis}, @ref{XREFcolormap,,colormap}}
@end deftypefn


@c surface scripts/plot/draw/surface.m
@anchor{XREFsurface}
@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}, @dots{})
@deftypefnx {Function File} {} surface (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} surface (@dots{})
Create a surface graphic object given matrices @var{x} and @var{y} from
@code{meshgrid} and a matrix of values @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 only a single input @var{z} is given then @var{x} is
taken to be @code{1:rows (@var{z})} and @var{y} is
@code{1:columns (@var{z})}.

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

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.
@seealso{@ref{XREFsurf,,surf}, @ref{XREFmesh,,mesh}, @ref{XREFpatch,,patch}, @ref{XREFline,,line}}
@end deftypefn


@subsubsection Handle Functions
@cindex handle functions

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

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

@var{h} may also be a matrix of handles in which case a logical
array is returned that is true where the elements of @var{h} are
graphics handles and false where they are not.
@seealso{@ref{XREFisaxes,,isaxes}, @ref{XREFisfigure,,isfigure}}
@end deftypefn


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

This function is equivalent to @code{ishandle} and is provided for
compatibility with @sc{matlab}.
@seealso{@ref{XREFishandle,,ishandle}}
@end deftypefn


@c isaxes scripts/plot/util/isaxes.m
@anchor{XREFisaxes}
@deftypefn {Function File} {} isaxes (@var{h})
Return true if @var{h} is an axes graphics handle and false otherwise.

If @var{h} is a matrix then return a logical array which is true where
the elements of @var{h} are axes graphics handles and false where
they are not.
@seealso{@ref{XREFisaxes,,isaxes}, @ref{XREFishandle,,ishandle}}
@end deftypefn


@c isfigure scripts/plot/util/isfigure.m
@anchor{XREFisfigure}
@deftypefn {Function File} {} isfigure (@var{h})
Return true if @var{h} is a figure graphics handle and false otherwise.

If @var{h} is a matrix then return a logical array which is true where
the elements of @var{h} are figure graphics handles and false where
they are not.
@seealso{@ref{XREFisaxes,,isaxes}, @ref{XREFishandle,,ishandle}}
@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 gcf scripts/plot/util/gcf.m
@anchor{XREFgcf}
@deftypefn {Function File} {@var{h} =} gcf ()
Return a handle to the current figure.

The current figure is the default target for graphics output.  If multiple
figures exist, @code{gcf} returns the last created figure or the last figure
that was clicked on with the mouse.

If a current figure does not exist, create one and return its handle.  The
handle may then be used to examine or set properties of the figure.  For
example,

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

@noindent
plots a sine wave, finds the handle of the current figure, and then
renames the figure window to describe the contents.

Note: To find the current figure without creating a new one if it does not
exist, query the @qcode{"CurrentFigure"} property of the root graphics
object.

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

@seealso{@ref{XREFgca,,gca}, @ref{XREFgco,,gco}, @ref{XREFgcbf,,gcbf}, @ref{XREFgcbo,,gcbo}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c gca scripts/plot/util/gca.m
@anchor{XREFgca}
@deftypefn {Function File} {@var{h} =} gca ()
Return a handle to the current axis object.

The current axis is the default target for graphics output.  In the case
of a figure with multiple axes, @code{gca} returns the last created axes
or the last axes that was clicked on with the mouse.

If no current axes object exists, create one and return its handle.  The
handle may then be used to examine or set properties of the axes.  For
example,

@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 and then changes its location and size in the
figure window.

Note: To find the current axis without creating a new axes object if it
does not exist, query the @qcode{"CurrentAxes"} property of a figure.

@example
get (gcf, "currentaxes");
@end example
@seealso{@ref{XREFgcf,,gcf}, @ref{XREFgco,,gco}, @ref{XREFgcbf,,gcbf}, @ref{XREFgcbo,,gcbo}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c gco scripts/plot/util/gco.m
@anchor{XREFgco}
@deftypefn  {Function File} {@var{h} =} gco ()
@deftypefnx {Function File} {@var{h} =} gco (@var{fig})
Return a handle to the current object of the current figure, or a handle
to the current object of the figure with handle @var{fig}.

The current object of a figure is the object that was last clicked on.  It
is stored in the @qcode{"CurrentObject"} property of the target figure.

If the last mouse click did not occur on any child object of the figure,
then the current object is the figure itself.

If no mouse click occurred in the target figure, this function returns an
empty matrix.

Programming Note: The value returned by this function is not necessarily the
same as the one returned by @code{gcbo} during callback execution.  An
executing callback can be interrupted by another callback and the current
object may be changed.

@seealso{@ref{XREFgcbo,,gcbo}, @ref{XREFgca,,gca}, @ref{XREFgcf,,gcf}, @ref{XREFgcbf,,gcbf}, @ref{XREFget,,get}, @ref{XREFset,,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 get libinterp/corefcn/graphics.cc
@anchor{XREFget}
@deftypefn  {Built-in Function} {@var{val} =} get (@var{h})
@deftypefnx {Built-in Function} {@var{val} =} get (@var{h}, @var{p})
Return the value of 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.
@seealso{@ref{XREFset,,set}}
@end deftypefn


@c set libinterp/corefcn/graphics.cc
@anchor{XREFset}
@deftypefn  {Built-in Function} {} set (@var{h}, @var{property}, @var{value}, @dots{})
@deftypefnx {Built-in Function} {} set (@var{h}, @var{properties}, @var{values})
@deftypefnx {Built-in Function} {} set (@var{h}, @var{pv})
Set named property values for the graphics handle (or vector of graphics
handles) @var{h}.
There are three ways how to give the property names and values:

@itemize
@item as a comma separated list of @var{property}, @var{value} pairs

Here, each @var{property} is a string containing the property name, each
@var{value} is a value of the appropriate type for the property.

@item as a cell array of strings @var{properties} containing property names
and a cell array @var{values} containing property values.

In this case, the number of columns of @var{values} must match the number of
elements in @var{properties}.  The first column of @var{values} contains
values for the first entry in @var{properties}, etc.  The number of rows of
@var{values} must be 1 or match the number of elements of @var{h}.  In the
first case, each handle in @var{h} will be assigned the same values.  In the
latter case, the first handle in @var{h} will be assigned the values from
the first row of @var{values} and so on.

@item as a structure array @var{pv}

Here, the field names of @var{pv} represent the property names, and the field
values give the property values.  In contrast to the previous case, all
elements of @var{pv} will be set in all handles in @var{h} independent of
the dimensions of @var{pv}.
@end itemize
@seealso{@ref{XREFget,,get}}
@end deftypefn


@c ancestor scripts/plot/util/ancestor.m
@anchor{XREFancestor}
@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} itself is of type @var{type}, return @var{h}.

If @qcode{"toplevel"} is given as a third argument, return the highest
parent in the object hierarchy that matches the condition, instead
of the first (nearest) one.
@seealso{@ref{XREFfindobj,,findobj}, @ref{XREFfindall,,findall}, @ref{XREFallchild,,allchild}}
@end deftypefn


@c allchild scripts/plot/util/allchild.m
@anchor{XREFallchild}
@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
hidden objects (HandleVisibility = @qcode{"off"}).  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{XREFfindall,,findall}, @ref{XREFfindobj,,findobj}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c findfigs scripts/plot/util/findfigs.m
@anchor{XREFfindfigs}
@deftypefn {Function File} {} findfigs ()
Find all visible figures that are currently off the screen and move them
onto the screen.
@seealso{@ref{XREFallchild,,allchild}, @ref{XREFfigure,,figure}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@cindex saving graphics objects
@cindex graphics objects, saving

Figures can be printed or saved in many graphics formats with @code{print} and
@code{saveas}.  Occasionally, however, it may be useful to save the original
Octave handle graphic directly so that further modifications can be made such
as modifying a title or legend.

This can be accomplished with the following functions by

@example
@group
fig_struct = hdl2struct (gcf);
save myplot.fig -struct fig_struct;
@dots{}
fig_struct = load ("myplot.fig");
struct2hdl (fig_struct);
@end group
@end example

@c hdl2struct scripts/plot/util/hdl2struct.m
@anchor{XREFhdl2struct}
@deftypefn {Function File} {@var{s} =} hdl2struct (@var{h})
Return a structure, @var{s}, whose fields describe the properties
of the object, and its children, associated with the handle, @var{h}.

The fields of the structure @var{s} are @qcode{"type"}, @qcode{"handle"},
@qcode{"properties"}, @qcode{"children"}, and @qcode{"special"}.
@seealso{@ref{XREFstruct2hdl,,struct2hdl}, @ref{XREFfindobj,,findobj}}
@end deftypefn


@c struct2hdl scripts/plot/util/struct2hdl.m
@anchor{XREFstruct2hdl}
@deftypefn  {Function File} {@var{h} =} struct2hdl (@var{s})
@deftypefnx {Function File} {@var{h} =} struct2hdl (@var{s}, @var{p})
@deftypefnx {Function File} {@var{h} =} struct2hdl (@var{s}, @var{p}, @var{hilev})
Construct a graphics handle object @var{h} from the structure @var{s}.

The structure must contain the fields @qcode{"handle"}, @qcode{"type"},
@qcode{"children"}, @qcode{"properties"}, and @qcode{"special"}.  If the
handle of an existing figure or axes is specified, @var{p}, the new object
will be created as a child of that object.  If no parent handle is provided
then a new figure and the necessary children will be constructed using the
default values from the root figure.

A third boolean argument @var{hilev} can be passed to specify whether
the function should preserve listeners/callbacks, e.g., for legends or
hggroups.  The default is false.
@seealso{@ref{XREFhdl2struct,,hdl2struct}, @ref{XREFfindobj,,findobj}}
@end deftypefn


@c copyobj scripts/plot/util/copyobj.m
@anchor{XREFcopyobj}
@deftypefn  {Function File} {@var{hnew} =} copyobj (@var{horig})
@deftypefnx {Function File} {@var{hnew} =} copyobj (@var{horig}, @var{hparent})
Construct a copy of the graphic object associated with handle @var{horig}
and return a handle @var{hnew} to the new object.

If a parent handle @var{hparent} (root, figure, axes, or hggroup) is
specified, the copied object will be created as a child of @var{hparent}.
@seealso{@ref{XREFstruct2hdl,,struct2hdl}, @ref{XREFhdl2struct,,hdl2struct}, @ref{XREFfindobj,,findobj}}
@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::
@end menu

In this Section the object properties are discussed in detail, starting
with the root figure properties and continuing through the graphics object
hierarchy.

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

The @code{root figure} properties are:

@table @code
@item __modified__
--- Values: @qcode{"on"}, @qcode{"off"}

@item __myhandle__

@item beingdeleted
--- Values: @qcode{"on"}, @qcode{"off"}

@item busyaction

@item buttondownfcn

@item callbackobject

@item children

@item clipping
 --- Values: @qcode{"on"}, @qcode{"off"}

@item createfcn

@item currentfigure

@item deletefcn

@item handlevisibility
--- Values: @qcode{"on"}, @qcode{"off"}

@item hittest
--- Values: @qcode{"on"}, @qcode{"off"}

@item interruptible
--- Values: @qcode{"on"}, @qcode{"off"}

@item parent

@item screendepth

@item screenpixelsperinch

@item screensize

@item selected

@item selectionhighlight

@item screendepth

@item screenpixelsperinch

@item showhiddenhandles
--- Values: @qcode{"on"}, @qcode{"off"}

@item tag

@item type

@item uicontextmenu

@item units

@item userdata

@item visible
@end table

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

The @code{figure} properties are:

@table @code
@item __graphics_toolkit__
--- The graphics toolkit currently in use.

@item __enhanced__

@item __modified__

@item __myhandle__

@item __plot_stream__

@item alphamap

@item beingdeleted
--- Values: @qcode{"on"}, @qcode{"off"}

@item busyaction

@item buttondownfcn

@item children
Handle to children.

@item clipping
--- Values: @qcode{"on"}, @qcode{"off"}

@item closerequestfcn
--- Handle of function to call on close.

@item color

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

@item paperorientation

@item createfcn

@item currentaxes
Handle to graphics object of current axes.

@item currentcharacter

@item currentobject

@item currentpoint
Holds the coordinates of the point over which the mouse pointer was when
the mouse button was pressed.  If a mouse callback function is defined,
@qcode{"currentpoint"} holds the coordinates of the point over which the
mouse pointer is when the function gets called.

@item deletefcn

@item dockcontrols
--- Values: @qcode{"on"}, @qcode{"off"}

@item doublebuffer
--- Values: @qcode{"on"}, @qcode{"off"}

@item filename

@item handlevisibility
--- Values: @qcode{"on"}, @qcode{"off"}

@item hittest

@item integerhandle

@item interruptible
--- Values: @qcode{"on"}, @qcode{"off"}

@item inverthardcopy

@item keypressfcn
see @qcode{"keypressfcn"}

@item keyreleasefcn
With @qcode{"keypressfcn"}, the keyboard callback functions.  These
callback functions get called when a key is pressed/released
respectively.  The functions are called with two input arguments.  The
first argument holds the handle of the calling figure.  The second
argument holds the event structure which has the following members:

@table @code
@item Character
The ASCII value of the key

@item Key
lowercase value of the key

@item Modifier
A cell array containing strings representing the modifiers pressed with
the key.  Possible values are @qcode{"shift"}, @qcode{"alt"}, and
@qcode{"control"}.
@end table

@item menubar

@item mincolormap

@item name

@item nextplot
May be one of

@table @asis
@item @qcode{"new"}

@item @qcode{"add"}

@item @qcode{"replace"}

@item @qcode{"replacechildren"}
@end table

@item numbertitle

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

@item paperposition

@item paperpositionmode

@item papersize

@item papertype

@item paperunits

@item pointer

@item pointershapecdata

@item pointershapehotspot

@item position

@item renderer

@item renderermode

@item resize

@item resizefcn

@item selected

@item selectionhighlight
--- Values: @qcode{"on"}, @qcode{"off"}

@item selectiontype

@item tag

@item toolbar

@item type

@item units

@item userdata

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

@item windowbuttondownfcn
See @qcode{"windowbuttonupfcn"}

@item windowbuttonmotionfcn
See @qcode{"windowbuttonupfcn"}

@item windowbuttonupfcn
With @qcode{"windowbuttondownfcn"} and @qcode{"windowbuttonmotionfcn"},
the mouse callback functions.  These callback functions get called when
the mouse button is pressed, dragged, and released respectively.  When
these callback functions are called, the @qcode{"currentpoint"} property
holds the current coordinates of the cursor.

@item windowscrollwheelfcn

@item windowstyle

@item wvisual

@item wvisualmode

@item xdisplay

@item xvisual

@item xvisualmode
@end table

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

The @code{axes} properties are:

@table @code
@item __modified__

@item __myhandle__

@item activepositionproperty

@item alim

@item alimmode

@item ambientlightcolor

@item beingdeleted

@item box
Box surrounding axes.
--- Values: @qcode{"on"}, @qcode{"off"}

@item busyaction

@item buttondownfcn

@item cameraposition

@item camerapositionmode

@item cameratarget

@item cameratargetmode

@item cameraupvector

@item cameraupvectormode

@item cameraviewangle

@item cameraviewanglemode

@item children

@item clim
Two-element vector defining the limits for the c axis of
an image.  See @code{pcolor} property.
Setting this property also forces the corresponding mode
property to be set to @qcode{"manual"}.

@item climmode
Either @qcode{"manual"} or @qcode{"auto"}.

@item clipping

@item color

@item colororder

@item createfcn

@item currentpoint
Holds the coordinates of the point over which the mouse pointer was when
the mouse button was pressed.  If a mouse callback function is defined,
@qcode{"currentpoint"} holds the coordinates of the point over which the
mouse pointer is when the function gets called.

@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 @qcode{"manual"}.

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

@item deletefcn

@item drawmode

@item fontangle

@item fontname

@item fontsize

@item fontunits

@item fontweight

@item gridlinestyle

@item handlevisibility

@item hittest

@item interpreter

@item interruptible

@item layer

@item linestyleorder

@item linewidth

@item minorgridlinestyle

@item nextplot
May be one of

@table @asis
@item @qcode{"add"}

@item @qcode{"replace"}

@item @qcode{"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.

@item parent

@item plotboxaspectratio

@item plotboxaspectratiomode

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

@item selected

@item selectionhighlight

@item tag

@item tickdir

@item tickdirmode

@item ticklength

@item tightinset

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

@item type

@item uicontextmenu

@item units

@item userdata

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

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

@item x_normrendertransform

@item x_projectiontransform

@item x_rendertransform

@item x_viewporttransform

@item x_viewtransform

@item xaxislocation
Either @qcode{"top"} or @qcode{"bottom"}.

@item xcolor

@item xdir
Either @qcode{"forward"} or @qcode{"reverse"}.

@item xgrid
Either @qcode{"on"} or @qcode{"off"} to toggle display of grid lines.

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

@item xlim
Two-element vector defining the limits for the x-axis.
Setting this property also forces the corresponding mode
property to be set to @qcode{"manual"}.

@item xlimmode
Either @qcode{"manual"} or @qcode{"auto"}.

@item xminorgrid
Either @qcode{"on"} or @qcode{"off"} to toggle display of minor grid lines.

@item xminortick

@item xscale
Either @qcode{"linear"} or @qcode{"log"}.

@item xtick
Set position of tick marks.
Setting this property also forces the corresponding mode
property to be set to @qcode{"manual"}.

@item xticklabel
Setting this property also forces the corresponding mode
property to be set to @qcode{"manual"}.

@item xticklabelmode
Either @qcode{"manual"} or @qcode{"auto"}.

@item xtickmode
Either @qcode{"manual"} or @qcode{"auto"}.

@item yaxislocation
Either @qcode{"left"} or @qcode{"right"}

@item ycolor

@item ydir
Either @qcode{"forward"} or @qcode{"reverse"}.

@item ygrid
Either @qcode{"on"} or @qcode{"off"} to toggle display of grid lines.

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

@item ylim
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 @qcode{"manual"}.

@item ylimmode
Either @qcode{"manual"} or @qcode{"auto"}.

@item yminorgrid
Either @qcode{"on"} or @qcode{"off"} to toggle display of minor grid lines.

@item yminortick

@item yscale
Either @qcode{"linear"} or @qcode{"log"}.

@item ytick
Set position of tick marks.
Setting this property also forces the corresponding mode
property to be set to @qcode{"manual"}.

@item yticklabel
Setting this property also forces the corresponding mode
property to be set to @qcode{"manual"}.

@item yticklabelmode
Either @qcode{"manual"} or @qcode{"auto"}.

@item ytickmode
Either @qcode{"manual"} or @qcode{"auto"}.

@item zcolor

@item zdir
Either @qcode{"forward"} or @qcode{"reverse"}.

@item zgrid
Either @qcode{"on"} or @qcode{"off"} to toggle display of grid lines.

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

@item zlim
Two-element vector defining the limits for z-axis.
Setting this property also forces the corresponding mode
property to be set to @qcode{"manual"}.

@item zlimmode
Either @qcode{"manual"} or @qcode{"auto"}.

@item zminorgrid
Either @qcode{"on"} or @qcode{"off"} to toggle display of minor grid lines.

@item zminortick

@item zscale
Either @qcode{"linear"} or @qcode{"log"}.

@item ztick
Set position of tick marks.
Setting this property also forces the corresponding mode
property to be set to @qcode{"manual"}.

@item zticklabel
Setting this property also forces the corresponding mode
property to be set to @qcode{"manual"}.

@item zticklabelmode
Either @qcode{"manual"} or @qcode{"auto"}.

@item ztickmode
Either @qcode{"manual"} or @qcode{"auto"}.

@end table

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

The @code{line} properties are:

@table @code
@item __modified__

@item __myhandle__

@item beingdeleted

@item busyaction

@item buttondownfcn

@item children

@item clipping

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

@item createfcn

@item deletefcn

@item displayname
The text of the legend entry corresponding to this line.

@item erasemode

@item handlevisibility

@item hittest

@item interpreter

@item interruptible

@item ldata
The lower errorbar in the y direction to be plotted.

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

@item linewidth

@item marker

@item markeredgecolor

@item markerfacecolor

@item markersize
@xref{Marker Styles}.

@item parent

@item selected

@item selectionhighlight

@item tag

@item type

@item udata
The upper errorbar in the y direction to be plotted.

@item uicontextmenu

@item userdata

@item visible

@item xdata
The data to be plotted.

@item xdatasource

@item xldata
The lower errorbar to be plotted.

@item xlim

@item xliminclude

@item xudata
The upper errorbar to be plotted.

@item ydata
The data to be plotted.

@item ydatasource

@item ylim

@item yliminclude

@item zdata
The data to be plotted.

@item zdatasource

@item zlim

@item zliminclude
@end table

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

The @code{text} properties are:

@table @code
@item __modified__

@item __myhandle__

@item backgroundcolor

@item beingdeleted

@item busyaction

@item buttondownfcn

@item children

@item clipping

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

@item createfcn

@item deletefcn

@item displayname
The text of the legend entry corresponding to this line.

@item edgecolor

@item editing

@item erasemode

@item fontangle
Flag whether the font is italic or normal.  Valid values are @qcode{"normal"},
@qcode{"italic"}, and @qcode{"oblique"}.

@item fontname
The font used for the text.

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

@item fontunits

@item fontweight
Flag whether the font is bold, etc.  Valid values are @qcode{"normal"},
@qcode{"bold"}, @qcode{"demi"}, or @qcode{"light"}.

@item handlevisibility

@item hittest

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

@item interpreter
Determines how the text is rendered.  Valid values are @qcode{"none"},
@qcode{"tex"}, or @qcode{"latex"}.

@item interruptible

@item linestyle

@item linewidth

@item margin

@item parent

@item position
The coordinates of the text object.

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

@item selected

@item selectionhighlight

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

@item tag

@item type

@item uicontextmenu

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

@item userdata

@item verticalalignment

@item visible

@item xlim

@item xliminclude

@item ylim

@item yliminclude

@item zlim

@item zliminclude

@end table

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

The @code{image} properties are:

@table @code
@item __modified__

@item __myhandle__

@item beingdeleted

@item busyaction

@item buttondownfcn

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

@item children

@item clim

@item climinclude

@item clipping

@item createfcn

@item deletefcn

@item handlevisibility

@item hittest

@item interruptible

@item parent

@item selected

@item selectionhighlight

@item tag

@item type

@item uicontextmenu

@item userdata

@item visible

@item xdata
Two-element vector specifying the range of the x-coordinates for
the image.

@item xlim

@item xliminclude

@item ydata
Two-element vector specifying the range of the y-coordinates for
the image.

@item ylim

@item yliminclude
@end table

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

The @code{patch} properties are:

@table @code
@item __modified__

@item __myhandle__

@item alim

@item aliminclude

@item alphadatamapping

@item ambientstrength

@item backfacelighting

@item beingdeleted

@item busyaction

@item buttondownfcn

@item cdata
Data defining the patch object.

@item cdatamapping

@item children

@item clim

@item climinclude

@item clipping

@item createfcn

@item deletefcn

@item diffusestrength

@item displayname
The text of the legend entry corresponding to this line.

@item edgealpha

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

@item edgelighting

@item erasemode

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

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

@item facelighting

@item faces

@item facevertexalphadata

@item facevertexcdata

@item handlevisibility

@item hittest

@item interpreter

@item interruptible

@item linestyle
@xref{Line Styles}.

@item linewidth
@xref{Line Styles}.

@item marker
@xref{Marker Styles}.

@item markeredgecolor
@xref{Marker Styles}.

@item markerfacecolor
@xref{Marker Styles}.

@item markersize
@xref{Marker Styles}.

@item normalmode

@item parent

@item selected

@item selectionhighlight

@item specularcolorreflectance

@item specularexponent

@item specularstrength

@item tag

@item type

@item uicontextmenu

@item userdata

@item vertexnormals

@item vertices

@item visible

@item xdata
Data defining the patch object.

@item xlim

@item xliminclude

@item ydata
Data defining the patch object.

@item ylim

@item yliminclude

@item zdata
Data defining the patch object.

@item zlim

@item zliminclude

@end table

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

The @code{surface} properties are:

@table @code
@item __modified__

@item __myhandle__

@item alim

@item aliminclude

@item alphadata

@item alphadatamapping

@item ambientstrength

@item backfacelighting

@item beingdeleted

@item busyaction

@item buttondownfcn

@item cdata

@item cdatamapping

@item cdatasource

@item children

@item clim

@item climinclude

@item clipping

@item createfcn

@item deletefcn

@item diffusestrength

@item displayname
The text of the legend entry corresponding to this surface.

@item edgealpha

@item edgecolor

@item edgelighting

@item erasemode

@item facealpha

@item facecolor

@item facelighting

@item handlevisibility

@item hittest

@item interpreter

@item interruptible

@item linestyle

@item linewidth

@item marker

@item markeredgecolor

@item markerfacecolor

@item markersize

@item meshstyle

@item normalmode

@item parent

@item selected

@item selectionhighlight

@item specularcolorreflectance

@item specularexponent

@item specularstrength

@item tag

@item type

@item uicontextmenu

@item userdata

@item vertexnormals

@item visible

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

@item xdatasource

@item xlim

@item xliminclude

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

@item ydatasource

@item ylim

@item yliminclude

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

@item zdatasource

@item zlim

@item zliminclude
@end table

@node Searching Properties
@subsection Searching Properties

@c findobj scripts/plot/util/findobj.m
@anchor{XREFfindobj}
@deftypefn  {Function File} {@var{h} =} findobj ()
@deftypefnx {Function File} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, @dots{})
@deftypefnx {Function File} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @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 (@var{hlist}, @dots{})
@deftypefnx {Function File} {@var{h} =} findobj (@var{hlist}, "flat", @dots{})
@deftypefnx {Function File} {@var{h} =} findobj (@var{hlist}, "-depth", @var{d}, @dots{})
Find graphics object with specified property values.

The simplest form is

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

@noindent
which returns the handles of all objects which have a property named
@var{prop_name} that has the value @var{prop_value}.  If multiple
property/value pairs are specified then only objects meeting all of the
conditions are returned.

The search can be limited to a particular set of objects and their
descendants, by passing a handle or set of handles @var{hlist} as the first
argument.

The depth of the object hierarchy to search can be limited with the
@qcode{"-depth"} argument.  An example of searching only three generations
of children is:

@example
findobj (@var{hlist}, "-depth", 3, @var{prop_name}, @var{prop_value})
@end example

Specifying a depth @var{d} of 0, limits the search to the set of objects
passed in @var{hlist}.  A depth @var{d} of 0 is equivalent to the
@qcode{"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:
@qcode{"-and"}, @qcode{"-or"},
@qcode{"-xor"}, @qcode{"-not"}.

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 by using the
@qcode{"-property"} option.

Implementation Note: The search only includes objects with visible
handles (HandleVisibility = @qcode{"on"}).  @xref{XREFfindall,,findall}, to
search for all objects including hidden ones.
@seealso{@ref{XREFfindall,,findall}, @ref{XREFallchild,,allchild}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c findall scripts/plot/util/findall.m
@anchor{XREFfindall}
@deftypefn  {Function File} {@var{h} =} findall ()
@deftypefnx {Function File} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, @dots{})
@deftypefnx {Function File} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @var{prop_name}, @var{prop_value})
@deftypefnx {Function File} {@var{h} =} findall ("-property", @var{prop_name})
@deftypefnx {Function File} {@var{h} =} findall ("-regexp", @var{prop_name}, @var{pattern})
@deftypefnx {Function File} {@var{h} =} findall (@var{hlist}, @dots{})
@deftypefnx {Function File} {@var{h} =} findall (@var{hlist}, "flat", @dots{})
@deftypefnx {Function File} {@var{h} =} findall (@var{hlist}, "-depth", @var{d}, @dots{})
Find graphics object, including hidden ones, with specified property values.

The return value @var{h} is a list of handles to the found graphic objects.

@code{findall} performs the same search as @code{findobj}, but it
includes hidden objects (HandleVisibility = @qcode{"off"}).  For full
documentation, @pxref{XREFfindobj,,findobj}.
@seealso{@ref{XREFfindobj,,findobj}, @ref{XREFallchild,,allchild}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@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, of the specified object type.
For example, setting the default @code{color} property of @code{line}
objects to @qcode{"green"}, for the @code{root} object, will result in all
@code{line} objects inheriting the @code{color} @qcode{"green"} as the default
value.

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

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

@noindent
removes the user-defined default line color setting from the current axes
object.  To quickly remove all user-defined defaults use the @code{reset}
function.

@c reset libinterp/corefcn/graphics.cc
@anchor{XREFreset}
@deftypefn {Built-in Function} {} reset (@var{h}, @var{property})
Remove any defaults set for the handle @var{h}.  The default figure
properties of @qcode{"position"}, @qcode{"units"},
@qcode{"windowstyle"} and @qcode{"paperunits"} and the default axes
properties of @qcode{"position"} and @qcode{"units"} are not reset.
@seealso{@ref{XREFcla,,cla}, @ref{XREFclf,,clf}}
@end deftypefn


Getting the @qcode{"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 Advanced Plotting
@section Advanced Plotting


@menu
* Colors::
* Line Styles::
* Marker Styles::
* Callbacks::
* Application-defined Data::
* Object Groups::
* Graphics Toolkits::
@end menu


@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 @qcode{"blue"},
@qcode{"black"}, @qcode{"cyan"}, @qcode{"green"}, @qcode{"magenta"},
@qcode{"red"}, @qcode{"white"}, and @qcode{"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 line.  [default]

@item "--"
Dashed line.

@item ":"
Dotted line.

@item "-."
A dash-dot line.

@item @qcode{"none"}
No line.  Points will still be marked using the current Marker Style.
@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
@qcode{"none"}, meaning no markers should be displayed.

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

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

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

The @code{colstyle} function will parse a @code{plot}-style specification
and will return the color, line, and marker values that would result.

@c colstyle scripts/plot/util/colstyle.m
@anchor{XREFcolstyle}
@deftypefn {Function File} {[@var{style}, @var{color}, @var{marker}, @var{msg}] =} colstyle (@var{linespec})
Parse @var{linespec} and return the line style, color, and markers given.
In the case of an error, the string @var{msg} will return the text of the
error.
@end deftypefn


@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

@noindent
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 gcbo scripts/plot/util/gcbo.m
@anchor{XREFgcbo}
@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 @qcode{"CallbackObject"}.

When called with a second output argument, return the handle of the figure
containing the object whose callback is currently executing.  If no callback
is executing the second output is also set to the empty matrix.

@seealso{@ref{XREFgcbf,,gcbf}, @ref{XREFgco,,gco}, @ref{XREFgca,,gca}, @ref{XREFgcf,,gcf}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c gcbf scripts/plot/util/gcbf.m
@anchor{XREFgcbf}
@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 @code{gcbo}.

@seealso{@ref{XREFgcbo,,gcbo}, @ref{XREFgcf,,gcf}, @ref{XREFgco,,gco}, @ref{XREFgca,,gca}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


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

@node Application-defined Data
@subsection Application-defined Data
@cindex application-defined data

Octave has a provision for attaching application-defined data to a graphics
handle.  The data can be anything which is meaningful to the application, and
will be completely ignored by Octave.

@c setappdata scripts/miscellaneous/setappdata.m
@anchor{XREFsetappdata}
@deftypefn {Function File} {} setappdata (@var{h}, @var{name}, @var{value})
Set the named application data to @var{value} for the object(s) with
handle(s) @var{h}.  If the application data with the specified name does
not exist, it is created.
@seealso{@ref{XREFgetappdata,,getappdata}, @ref{XREFguidata,,guidata}, @ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFgetpref,,getpref}, @ref{XREFsetpref,,setpref}}
@end deftypefn


@c getappdata scripts/miscellaneous/getappdata.m
@anchor{XREFgetappdata}
@deftypefn  {Function File} {@var{value} =} getappdata (@var{h}, @var{name})
@deftypefnx {Function File} {@var{appdata} =} getappdata (@var{h})

Return the @var{value} for named application data for the object(s) with
handle(s) @var{h}.

@code{getappdata(@var{h})} returns a structure, @var{appdata}, whose fields
correspond to the appdata properties.

@seealso{@ref{XREFsetappdata,,setappdata}, @ref{XREFguidata,,guidata}, @ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFgetpref,,getpref}, @ref{XREFsetpref,,setpref}}
@end deftypefn


@c rmappdata scripts/miscellaneous/rmappdata.m
@anchor{XREFrmappdata}
@deftypefn {Function File} {} rmappdata (@var{h}, @var{name})
Delete the named application data for the object(s) with
handle(s) @var{h}.
@end deftypefn


@c isappdata scripts/miscellaneous/isappdata.m
@anchor{XREFisappdata}
@deftypefn {Function File} {@var{V} =} isappdata (@var{h}, @var{name})
Return true if the named application data, @var{name}, exists for the
object with handle @var{h}.
@seealso{@ref{XREFgetappdata,,getappdata}, @ref{XREFsetappdata,,setappdata}, @ref{XREFrmappdata,,rmappdata}}
@end deftypefn


@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 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 hggroup scripts/plot/util/hggroup.m
@anchor{XREFhggroup}
@deftypefn  {Function File} {} hggroup ()
@deftypefnx {Function File} {} hggroup (@var{hax})
@deftypefnx {Function File} {} hggroup (@dots{}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{h} =} hggroup (@dots{})
Create handle graphics group object with axes parent @var{hax}.

If no parent is specified, the group is created in the current axes.

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

The optional return value @var{h} is a graphics handle to the created
hggroup object.

Programming Note: An hggroup is a way to group base graphics objects such
as line objects or patch objects into a single unit which can react
appropriately.  For example, the individual lines of a contour plot are
collected into a single hggroup so that they can be made visible/invisible
with a single command, @code{set (hg_handle, "visible", "off")}.

@seealso{@ref{XREFaddproperty,,addproperty}, @ref{XREFaddlistener,,addlistener}}
@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 addproperty libinterp/corefcn/graphics.cc
@anchor{XREFaddproperty}
@deftypefn  {Built-in Function} {} addproperty (@var{name}, @var{h}, @var{type})
@deftypefnx {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 @nospell{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

@seealso{@ref{XREFaddlistener,,addlistener}, @ref{XREFhggroup,,hggroup}}
@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 addlistener libinterp/corefcn/graphics.cc
@anchor{XREFaddlistener}
@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

@seealso{@ref{XREFaddproperty,,addproperty}, @ref{XREFhggroup,,hggroup}}
@end deftypefn


@c dellistener libinterp/corefcn/graphics.cc
@anchor{XREFdellistener}
@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 linkprop scripts/plot/util/linkprop.m
@anchor{XREFlinkprop}
@deftypefn  {Function File} {@var{hlink} =} linkprop (@var{h}, @var{prop})
@deftypefnx {Function File} {@var{hlink} =} linkprop (@var{h}, @{@var{prop1}, @var{prop2}, @dots{}@})
Link graphics object properties, such that a change in one is
propagated to the others.

@var{prop} can be a string for a single property, or a cell array of strings
for multiple properties.  @var{h} is an array of graphics handles which
will have their properties linked.

An example of the use of @code{linkprop} 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
@anchor{XREFdatasources}
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 refreshdata scripts/plot/util/refreshdata.m
@anchor{XREFrefreshdata}
@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 the first argument @var{h} is a list of graphic handles, then operate
on these objects rather than the current figure returned by @code{gcf}.

The optional second argument @var{workspace} can take the following values:

@table @asis
@item @qcode{"base"}
Evaluate the datasource properties in the base workspace.  (default).

@item @qcode{"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{XREFlinkdata}
@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 @qcode{"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 properties are propagated to the other members of
the bar series and to the baseline itself.  Equally, changes in the
properties of the base line itself are propagated to the members of the
corresponding bar series.

@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 @qcode{"grouped"} or @qcode{"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 @qcode{"on"} or @qcode{"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 @qcode{"none"},
@qcode{"auto"}, or @qcode{"manual"}.  When its value is @qcode{"none"} there is
no z component to the plotted contours.  When its value is @qcode{"auto"} the z
value of the plotted contours is at the same value as the contour itself.  If
the value is @qcode{"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 @qcode{"manual"}, then the levels at which to plot
the contours is determined by @code{levellist}.  If @code{levellistmode} is set
to @qcode{"auto"}, then the distance between contours is determined by
@code{levelstep}.  If both @code{levellistmode} and @code{levelstepmode} are
set to @qcode{"auto"}, then there are assumed to be 10 equal spaced contours.

@item  textlistmode
@itemx textlist
@itemx textstepmode
@itemx textstep
If @code{textlistmode} is @qcode{"manual"}, then the labeled contours
is determined by @code{textlist}.  If @code{textlistmode} is set to
@qcode{"auto"}, then the distance between labeled contours is determined by
@code{textstep}.  If both @code{textlistmode} and @code{textstepmode}
are set to @qcode{"auto"}, then there are assumed to be 10 equal spaced
labeled 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 @qcode{"none"} or @qcode{"auto"}.  If @code{linecolor} is
@qcode{"none"}, then no contour line is drawn.  If @code{linecolor} is
@qcode{"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 origin 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 @qcode{"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
@itemx cdata
The original x, y, z and c data.

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

@node Graphics Toolkits
@subsection Graphics Toolkits
@cindex graphics toolkits
@cindex toolkits, graphics

@c graphics_toolkit scripts/plot/util/graphics_toolkit.m
@anchor{XREFgraphics_toolkit}
@deftypefn  {Function File} {@var{name} =} graphics_toolkit ()
@deftypefnx {Function File} {@var{name} =} graphics_toolkit (@var{hlist})
@deftypefnx {Function File} {} graphics_toolkit (@var{name})
@deftypefnx {Function File} {} graphics_toolkit (@var{hlist}, @var{name})
Query or set the default graphics toolkit which is assigned to new figures.

With no inputs, return the current default graphics toolkit.  If the input
is a list of figure graphic handles, @var{hlist}, then return the name
of the graphics toolkit in use for each figure.

When called with a single input @var{name} set the default graphics toolkit
to @var{name}.  If the toolkit is not already loaded, it is initialized by
calling the function @code{__init_@var{name}__}.  If the first input
is a list of figure handles, @var{hlist}, then the graphics toolkit is set
to @var{name} for these figures only.

@seealso{@ref{XREFavailable_graphics_toolkits,,available_graphics_toolkits}}
@end deftypefn


@c available_graphics_toolkits libinterp/corefcn/graphics.cc
@anchor{XREFavailable_graphics_toolkits}
@deftypefn {Built-in Function} {} available_graphics_toolkits ()
Return a cell array of registered graphics toolkits.
@seealso{@ref{XREFgraphics_toolkit,,graphics_toolkit}, @ref{XREFregister_graphics_toolkit,,register_graphics_toolkit}}
@end deftypefn


@c loaded_graphics_toolkits libinterp/corefcn/graphics.cc
@anchor{XREFloaded_graphics_toolkits}
@deftypefn {Built-in Function} {} loaded_graphics_toolkits ()
Return a cell array of the currently loaded graphics toolkits.
@seealso{@ref{XREFavailable_graphics_toolkits,,available_graphics_toolkits}}
@end deftypefn


@c register_graphics_toolkit libinterp/corefcn/graphics.cc
@anchor{XREFregister_graphics_toolkit}
@deftypefn {Built-in Function} {} register_graphics_toolkit (@var{toolkit})
List @var{toolkit} as an available graphics toolkit.
@seealso{@ref{XREFavailable_graphics_toolkits,,available_graphics_toolkits}}
@end deftypefn


@menu
* Customizing Toolkit Behavior::
@end menu

@node Customizing Toolkit Behavior
@subsubsection Customizing Toolkit Behavior
@cindex toolkit customization

The specific behavior of the backend toolkit may be modified using the
following utility functions.  Note: Not all functions apply to every
graphics toolkit.

@c gnuplot_binary scripts/plot/util/gnuplot_binary.m
@anchor{XREFgnuplot_binary}
@deftypefn  {Loadable Function} {[@var{prog}, @var{args}] =} gnuplot_binary ()
@deftypefnx {Loadable Function} {[@var{old_prog}, @var{old_args}] =} gnuplot_binary (@var{new_prog}, @var{arg1}, @dots{})
Query or set the name of the program invoked by the plot command
when the graphics toolkit is set to "gnuplot".  Additional arguments to
pass to the external plotting program may also be given.
The default value is @qcode{"gnuplot"} with no additional arguments.
@xref{Installation}.
@seealso{@ref{XREFgraphics_toolkit,,graphics_toolkit}}
@end deftypefn


@c gui_mode libinterp/dldfcn/__init_fltk__.cc
@anchor{XREFgui_mode}
@deftypefn  {Built-in Function} {@var{mode} =} gui_mode ()
@deftypefnx {Built-in Function} {} gui_mode (@var{mode})
Query or set the GUI mode for the current graphics toolkit.
The @var{mode} argument can be one of the following strings:

@table @asis
@item @qcode{"2d"}
Allows panning and zooming of current axes.

@item @qcode{"3d"}
Allows rotating and zooming of current axes.

@item @qcode{"none"}
Mouse inputs have no effect.
@end table

This function is currently implemented only for the FLTK graphics toolkit.
@seealso{@ref{XREFmouse_wheel_zoom,,mouse_wheel_zoom}}
@end deftypefn


@c mouse_wheel_zoom libinterp/dldfcn/__init_fltk__.cc
@anchor{XREFmouse_wheel_zoom}
@deftypefn  {Loadable Function} {@var{val} =} mouse_wheel_zoom ()
@deftypefnx {Loadable Function} {@var{old_val} =} mouse_wheel_zoom (@var{new_val})
@deftypefnx {Loadable Function} {} mouse_wheel_zoom (@var{new_val}, "local")
Query or set the mouse wheel zoom factor.

The zoom factor is a number in the range (0,1) which is the percentage of the
current axis limits that will be used when zooming.  For example, if the
current x-axis limits are [0, 50] and @code{mouse_wheel_zoom} is 0.4 (40%),
then a zoom operation will change the limits by 20.

When called from inside a function with the @qcode{"local"} option, the
variable is changed locally for the function and any subroutines it calls.  
The original variable value is restored when exiting the function.

This function is currently implemented only for the FLTK graphics toolkit.
@seealso{@ref{XREFgui_mode,,gui_mode}}
@end deftypefn