File: plot.texi

package info (click to toggle)
octave 10.3.0-1
links: PTS, VCS
area: main
in suites:
size: 145,388 kB
sloc: cpp: 335,976; ansic: 82,241; fortran: 20,963; objc: 9,402; sh: 8,756; yacc: 4,392; lex: 4,333; perl: 1,544; java: 1,366; awk: 1,259; makefile: 659; xml: 192
file content (12287 lines) | stat: -rw-r--r-- 424,121 bytes
parent folder | download | duplicates (2)
@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

@c Copyright (C) 1996-2025 The Octave Project Developers
@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
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License 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 <https://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, newer versions of Octave offer more modern
plotting capabilities using OpenGL@.  Which plotting system is used is
controlled by the @code{graphics_toolkit} function.  @xref{Graphics Toolkits}.

The function call @code{graphics_toolkit ("qt")} selects the Qt/OpenGL system,
@code{graphics_toolkit ("fltk")} selects the FLTK/OpenGL system, and
@code{graphics_toolkit ("gnuplot")} selects the gnuplot system.  The three
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 OpenGL-based toolkits use 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}}.  Similarly,
single precision variables can accurately represent only 6-9 base10 digits.  If
your data contains very fine differences (approximately 1e-8) these cannot be
resolved with the OpenGL-based graphics toolkits and the gnuplot toolkit
is required.

@strong{Note:} The gnuplot graphics toolkit uses the third party program
gnuplot for plotting.  The communication from Octave to gnuplot is done via a
one-way pipe.  This has implications for performance and functionality.
Performance is significantly slower because the entire data set, which could
be many megabytes, must be passed to gnuplot over the pipe.  Functionality
is negatively affected because the pipe is one-way from Octave to gnuplot.
Octave has no way of knowing about user interactions with the plot window (be
it resizing, moving, closing, or anything else).  It is recommended not to
interact with (or close) a gnuplot window if you will access the figure from
Octave later on.

@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 Objects::
* Manipulation of Plot Windows::
* Use of the "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));
xlabel ("x");
ylabel ("sin (x)");
title ("Simple 2-D Plot");
@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} plot (@var{y})
@deftypefnx {} {} plot (@var{x}, @var{y})
@deftypefnx {} {} plot (@var{x}, @var{y}, @var{fmt})
@deftypefnx {} {} plot (@dots{}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} plot (@var{x1}, @var{y1}, @dots{}, @var{xn}, @var{yn})
@deftypefnx {} {} plot (@var{hax}, @dots{})
@deftypefnx {} {@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 either @var{x} or @var{y} is a scalar and the other is a vector, a
series of points are plotted at the coordinates defined by the scalar and
each element of the vector.

@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 full list of properties is documented at
@ref{Line Properties}.

The @var{fmt} format argument can also be used to control the plot style.
It is a string composed of four optional parts:
"<linestyle><marker><color><;displayname;>".
When a marker is specified, but no linestyle, only the markers are
plotted.  Similarly, if a linestyle is specified, but no marker, then
only lines are drawn.  If both are specified then lines and markers will
be plotted.  If no @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 marker

@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{|} @tab vertical line
@item @samp{_} @tab horizontal line
@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.21 0.79
@item @samp{k}, @qcode{"black"}   @tab blacK
@item @samp{r}, @qcode{"red"}     @tab Red
@item @samp{g}, @qcode{"green"}   @tab Green
@item @samp{b}, @qcode{"blue"}    @tab Blue
@item @samp{y}, @qcode{"yellow"}  @tab Yellow
@item @samp{m}, @qcode{"magenta"} @tab Magenta
@item @samp{c}, @qcode{"cyan"}    @tab Cyan
@item @samp{w}, @qcode{"white"}   @tab White
@end multitable

@item @qcode{";displayname;"}
The text between semicolons is used to set the @qcode{"displayname"}
property which determines the label used for the plot legend.

@end table

The @var{fmt} argument may also be used to assign legend labels.
To do so, include the desired label between semicolons after the
formatting sequence described above, e.g., @qcode{"+b;Data Series 3;"}.
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 axes,
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.

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} plotyy (@var{x1}, @var{y1}, @var{x2}, @var{y2})
@deftypefnx {} {} plotyy (@dots{}, @var{fcn})
@deftypefnx {} {} plotyy (@dots{}, @var{fun1}, @var{fun2})
@deftypefnx {} {} plotyy (@var{hax}, @dots{})
@deftypefnx {} {[@var{ax}, @var{h1}, @var{h2}] =} plotyy (@dots{})
Plot two sets of data with independent y-axes and a common x-axis.

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{fcn} argument, in which case the plots are
generated by @code{feval (@var{fcn}, @var{x}, @var{y})}.  @var{fcn} 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}.

The first argument @var{hax} can be an axes handle to the principal axes in
which to plot the @var{x1} and @var{y1} data.  It can also be a two-element
vector with the axes handles to the primary and secondary axes (see output
@var{ax}).

The return value @var{ax} is a vector with the axes 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

When using @code{plotyy} in conjunction with @code{subplot} make sure to
call @code{subplot} first and pass the resulting axes handle to
@code{plotyy}.  Do not call @code{subplot} with any of the axes handles
returned by @code{plotyy} or the other axes will be removed.

@xseealso{@ref{XREFplot,,plot}, @ref{XREFsubplot,,subplot}}
@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} semilogx (@var{y})
@deftypefnx {} {} semilogx (@var{x}, @var{y})
@deftypefnx {} {} semilogx (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} semilogx (@var{x}, @var{y}, @var{fmt})
@deftypefnx {} {} semilogx (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
rather than the current axes returned by @code{gca}.

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


@c semilogy scripts/plot/draw/semilogy.m
@anchor{XREFsemilogy}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} semilogy (@var{y})
@deftypefnx {} {} semilogy (@var{x}, @var{y})
@deftypefnx {} {} semilogy (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} semilogy (@var{x}, @var{y}, @var{fmt})
@deftypefnx {} {} semilogy (@var{h}, @dots{})
@deftypefnx {} {@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 axes,
rather than the current axes returned by @code{gca}.

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


@c loglog scripts/plot/draw/loglog.m
@anchor{XREFloglog}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} loglog (@var{y})
@deftypefnx {} {} loglog (@var{x}, @var{y})
@deftypefnx {} {} loglog (@var{x}, @var{y}, @var{prop}, @var{value}, @dots{})
@deftypefnx {} {} loglog (@var{x}, @var{y}, @var{fmt})
@deftypefnx {} {} loglog (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.
@xseealso{@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
randn ("state", 1);
hist (randn (10000, 1), 30);
xlabel ("Value");
ylabel ("Count");
title ("Histogram of 10,000 normally distributed random numbers");
@end group
@end example

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

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

@c bar scripts/plot/draw/bar.m
@anchor{XREFbar}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} bar (@var{y})
@deftypefnx {} {} bar (@var{x}, @var{y})
@deftypefnx {} {} bar (@dots{}, @var{w})
@deftypefnx {} {} bar (@dots{}, @var{style})
@deftypefnx {} {} bar (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} bar (@var{hax}, @dots{})
@deftypefnx {} {@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.  The full list of properties is documented at
@ref{Patch Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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 default color for bars is taken from the axes' @qcode{"ColorOrder"}
property.  The default color for bars when a histogram option
(@qcode{"hist"}, @qcode{"histc"} is used is the @qcode{"Colormap"} property
of either the axes or figure.  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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} barh (@var{y})
@deftypefnx {} {} barh (@var{x}, @var{y})
@deftypefnx {} {} barh (@dots{}, @var{w})
@deftypefnx {} {} barh (@dots{}, @var{style})
@deftypefnx {} {} barh (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} barh (@var{hax}, @dots{})
@deftypefnx {} {@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.  The full list of properties is documented at
@ref{Patch Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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,,@code{bar}}.
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} hist (@var{y})
@deftypefnx {} {} hist (@var{y}, @var{nbins})
@deftypefnx {} {} hist (@var{y}, @var{x})
@deftypefnx {} {} hist (@var{y}, @var{x}, @var{norm})
@deftypefnx {} {} hist (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} hist (@var{hax}, @dots{})
@deftypefnx {} {[@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 (difference between maximum and minimum value in @var{y}).
Extreme values are lumped into the first and last bins.  If @var{y} is a
matrix then plot a histogram where each bin contains one bar per input
column of @var{y}.

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

If the optional second argument is a vector, @var{x}, it defines the centers
of the bins.  The width of the bins is determined from the adjacent values
in the vector.  The total number of bins is @code{numel (@var{x})}.

If a third argument @var{norm} is provided, the histogram is normalized.
In case @var{norm} is a positive scalar, the resulting bars are normalized
to @var{norm}.  If @var{norm} is a vector of positive scalars of length
@code{columns (@var{y})}, then the resulting bar of @code{@var{y}(:,i)} is
normalized to @code{@var{norm}(i)}.

@example
@group
[nn, xx] = hist (rand (10, 3), 5, [1 2 3]);
sum (nn, 1)
@result{} ans =
      1   2   3
@end group
@end example

The histogram's appearance may be modified by specifying property/value
pairs to the underlying patch object.  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 full list of patch properties is documented at @ref{Patch Properties}.
property.  If not specified, the default colors for the histogram are taken
from the @qcode{"Colormap"} property of the axes or figure.

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

If an output is requested then no plot is made.  Instead, return the values
@var{nn} (numbers of elements) and @var{xx} (bin centers) such that
@code{bar (@var{xx}, @var{nn})} will plot the histogram.  If @var{y} is a
vector, @var{nn} and @var{xx} will be row vectors.  If @var{y} is an array,
@var{nn} will be a 2-D array with one column of element counts for each
column in @var{y}, and @var{xx} will be a column vector of bin centers.

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


@c stemleaf scripts/plot/draw/stemleaf.m
@anchor{XREFstemleaf}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} stemleaf (@var{x}, @var{caption})
@deftypefnx {} {} stemleaf (@var{x}, @var{caption}, @var{stem_sz})
@deftypefnx {} {@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:
Chapter 3, @cite{Exploratory Data Analysis} by @nospell{J. W. Tukey},
Addison-Wesley, 1977.
@xseealso{@ref{XREFhist,,hist}, @ref{XREFprintd,,printd}}
@end deftypefn


@c printd scripts/plot/util/printd.m
@anchor{XREFprintd}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} printd (@var{obj}, @var{filename})
@deftypefnx {} {@var{out_file} =} printd (@dots{})

Convert any object acceptable to @code{disp} into the format selected by
the suffix of @var{filename}.

If the optional output @var{out_file} is requested, the name of the created
file is returned.

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


@c stairs scripts/plot/draw/stairs.m
@anchor{XREFstairs}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} stairs (@var{y})
@deftypefnx {} {} stairs (@var{x}, @var{y})
@deftypefnx {} {} stairs (@dots{}, @var{style})
@deftypefnx {} {} stairs (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} stairs (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} stairs (@dots{})
@deftypefnx {} {[@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
(@code{@var{x} = 1:numel (@var{y})}).

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.  The full list of properties is documented at
@ref{Line Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes 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.
@xseealso{@ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFplot,,plot}, @ref{XREFstem,,stem}}
@end deftypefn


@c stem scripts/plot/draw/stem.m
@anchor{XREFstem}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} stem (@var{y})
@deftypefnx {} {} stem (@var{x}, @var{y})
@deftypefnx {} {} stem (@dots{}, @var{linespec})
@deftypefnx {} {} stem (@dots{}, "filled")
@deftypefnx {} {} stem (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} stem (@var{hax}, @dots{})
@deftypefnx {} {@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 @var{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.  The full list of properties is documented at
@ref{Line Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} stem3 (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} stem3 (@dots{}, @var{linespec})
@deftypefnx {} {} stem3 (@dots{}, "filled")
@deftypefnx {} {} stem3 (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} stem3 (@var{hax}, @dots{})
@deftypefnx {} {@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 @var{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.  The full list of properties is documented at
@ref{Line Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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,,@code{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.
@xseealso{@ref{XREFstem,,stem}, @ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFplot,,plot}}
@end deftypefn


@c scatter scripts/plot/draw/scatter.m
@anchor{XREFscatter}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} scatter (@var{x}, @var{y})
@deftypefnx {} {} scatter (@var{x}, @var{y}, @var{s})
@deftypefnx {} {} scatter (@var{x}, @var{y}, @var{s}, @var{c})
@deftypefnx {} {} scatter (@dots{}, @var{style})
@deftypefnx {} {} scatter (@dots{}, "filled")
@deftypefnx {} {} scatter (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} scatter (@var{hax}, @dots{})
@deftypefnx {} {@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 36 square
points is used (The marker size itself is @code{sqrt (s)}).

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; it 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.

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

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

Example:

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

Programming Note: The full list of properties is documented at
@ref{Scatter Properties}.
@xseealso{@ref{XREFscatter3,,scatter3}, @ref{XREFpatch,,patch}, @ref{XREFplot,,plot}}
@end deftypefn


@c plotmatrix scripts/plot/draw/plotmatrix.m
@anchor{XREFplotmatrix}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} plotmatrix (@var{x}, @var{y})
@deftypefnx {} {} plotmatrix (@var{x})
@deftypefnx {} {} plotmatrix (@dots{}, @var{style})
@deftypefnx {} {} plotmatrix (@var{hax}, @dots{})
@deftypefnx {} {[@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

When called with 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 axes,
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 axes objects.

@var{bigax} is a hidden axes object that surrounds the other axes, such
that the commands @code{xlabel}, @code{title}, etc., will be associated
with this hidden axes.

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

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


@c pareto scripts/plot/draw/pareto.m
@anchor{XREFpareto}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} pareto (@var{y})
@deftypefnx {} {} pareto (@var{y}, @var{x})
@deftypefnx {} {} pareto (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} rose (@var{theta})
@deftypefnx {} {} rose (@var{theta}, @var{nbins})
@deftypefnx {} {} rose (@var{theta}, @var{bins})
@deftypefnx {} {} rose (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} rose (@dots{})
@deftypefnx {} {[@var{th}, @var{r}] =} 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 in @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 axes,
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

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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} contour (@var{z})
@deftypefnx {} {} contour (@var{z}, @var{vn})
@deftypefnx {} {} contour (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} contour (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {} {} contour (@dots{}, @var{style})
@deftypefnx {} {} contour (@var{hax}, @dots{})
@deftypefnx {} {[@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 axes,
rather than the current axes returned by @code{gca}.

The optional output @var{c} contains 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:3;
y = 0:2;
z = y' * x;
contour (x, y, z, 2:3)
@end group
@end example

@xseealso{@ref{XREFezcontour,,ezcontour}, @ref{XREFcontourc,,contourc}, @ref{XREFcontourf,,contourf}, @ref{XREFcontour3,,contour3}, @ref{XREFclabel,,clabel}, @ref{XREFmeshc,,meshc}, @ref{XREFsurfc,,surfc}, @ref{XREFclim,,clim}, @ref{XREFcolormap,,colormap}, @ref{XREFplot,,plot}}

@end deftypefn


@c contourf scripts/plot/draw/contourf.m
@anchor{XREFcontourf}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} contourf (@var{z})
@deftypefnx {} {} contourf (@var{z}, @var{vn})
@deftypefnx {} {} contourf (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} contourf (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {} {} contourf (@dots{}, @var{style})
@deftypefnx {} {} contourf (@var{hax}, @dots{})
@deftypefnx {} {[@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 axes,
rather than the current axes returned by @code{gca}.

The optional output @var{c} contains 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
@xseealso{@ref{XREFezcontourf,,ezcontourf}, @ref{XREFcontour,,contour}, @ref{XREFcontourc,,contourc}, @ref{XREFcontour3,,contour3}, @ref{XREFclabel,,clabel}, @ref{XREFmeshc,,meshc}, @ref{XREFsurfc,,surfc}, @ref{XREFclim,,clim}, @ref{XREFcolormap,,colormap}, @ref{XREFplot,,plot}}
@end deftypefn


@c contourc scripts/plot/draw/contourc.m
@anchor{XREFcontourc}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{c} =} contourc (@var{z})
@deftypefnx {} {@var{c} =} contourc (@var{z}, @var{vn})
@deftypefnx {} {@var{c} =} contourc (@var{x}, @var{y}, @var{z})
@deftypefnx {} {@var{c} =} contourc (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {} {[@var{c}, @var{lev}] =} contourc (@dots{})
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:columns (@var{z})} and @var{y}
is taken to be @code{1:rows (@var{z})}.  The minimum data size is 2x2.

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 the
contour levels.

Example:

@smallexample
@group
x = 0:2;
y = x;
z = x' * y;
c = contourc (x, y, z, 2:3)
@result{} c =
        2.0000   1.0000   1.0000   2.0000   2.0000   3.0000   1.5000   2.0000
        4.0000   2.0000   2.0000   1.0000   1.0000   2.0000   2.0000   1.5000
@end group
@end smallexample
@xseealso{@ref{XREFcontour,,contour}, @ref{XREFcontourf,,contourf}, @ref{XREFcontour3,,contour3}, @ref{XREFclabel,,clabel}}
@end deftypefn


@c contour3 scripts/plot/draw/contour3.m
@anchor{XREFcontour3}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} contour3 (@var{z})
@deftypefnx {} {} contour3 (@var{z}, @var{vn})
@deftypefnx {} {} contour3 (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} contour3 (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {} {} contour3 (@dots{}, @var{style})
@deftypefnx {} {} contour3 (@var{hax}, @dots{})
@deftypefnx {} {[@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 axes,
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

@xseealso{@ref{XREFcontour,,contour}, @ref{XREFcontourc,,contourc}, @ref{XREFcontourf,,contourf}, @ref{XREFclabel,,clabel}, @ref{XREFmeshc,,meshc}, @ref{XREFsurfc,,surfc}, @ref{XREFclim,,clim}, @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
rand ("state", 2);
x = 0:0.1:10;
y = sin (x);
lerr = 0.1 .* rand (size (x));
uerr = 0.1 .* rand (size (x));
errorbar (x, y, lerr, uerr);
axis ([0, 10, -1.1, 1.1]);
xlabel ("x");
ylabel ("sin (x)");
title ("Errorbar plot of sin (x)");
@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} errorbar (@var{y}, @var{ey})
@deftypefnx {} {} errorbar (@var{y}, @dots{}, @var{fmt})
@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{ey})
@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {} {} errorbar (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {} {} errorbar (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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}.
@xseealso{@ref{XREFsemilogxerr,,semilogxerr}, @ref{XREFsemilogyerr,,semilogyerr}, @ref{XREFloglogerr,,loglogerr}, @ref{XREFplot,,plot}}
@end deftypefn


@c semilogxerr scripts/plot/draw/semilogxerr.m
@anchor{XREFsemilogxerr}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} semilogxerr (@var{y}, @var{ey})
@deftypefnx {} {} semilogxerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {} {} semilogxerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {} {} semilogxerr (@var{hax}, @dots{})
@deftypefnx {} {@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,,@code{errorbar}}, for
available formats and additional information.

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

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


@c semilogyerr scripts/plot/draw/semilogyerr.m
@anchor{XREFsemilogyerr}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} semilogyerr (@var{y}, @var{ey})
@deftypefnx {} {} semilogyerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {} {} semilogyerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {} {} semilogyerr (@var{hax}, @dots{})
@deftypefnx {} {@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,,@code{errorbar}}, for
available formats and additional information.

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

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


@c loglogerr scripts/plot/draw/loglogerr.m
@anchor{XREFloglogerr}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} loglogerr (@var{y}, @var{ey})
@deftypefnx {} {} loglogerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {} {} loglogerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {} {} loglogerr (@var{hax}, @dots{})
@deftypefnx {} {@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,,@code{errorbar}}, for
available formats and additional information.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.
@xseealso{@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
@group
polar (0:0.1:10*pi, 0:0.1:10*pi);
title ("Example polar plot from 0 to 10*pi");
@end group
@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} polar (@var{theta}, @var{rho})
@deftypefnx {} {} polar (@var{theta}, @var{rho}, @var{fmt})
@deftypefnx {} {} polar (@var{cplx})
@deftypefnx {} {} polar (@var{cplx}, @var{fmt})
@deftypefnx {} {} polar (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} polar (@dots{})
Create a 2-D plot from polar coordinates @var{theta} and @var{rho}.

The input @var{theta} is assumed to be radians and is converted to degrees
for plotting.  If you have degrees then you must convert
(@pxref{XREFcart2pol,,@code{cart2pol}}) to radians before passing the
data to this function.

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 axes,
rather than the current axes returned by @code{gca}.

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

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


@c pie scripts/plot/draw/pie.m
@anchor{XREFpie}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} pie (@var{x})
@deftypefnx {} {} pie (@dots{}, @var{explode})
@deftypefnx {} {} pie (@dots{}, @var{labels})
@deftypefnx {} {} pie (@var{hax}, @dots{})
@deftypefnx {} {@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 nonzero, "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 axes,
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.

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


@c pie3 scripts/plot/draw/pie3.m
@anchor{XREFpie3}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} pie3 (@var{x})
@deftypefnx {} {} pie3 (@dots{}, @var{explode})
@deftypefnx {} {} pie3 (@dots{}, @var{labels})
@deftypefnx {} {} pie3 (@var{hax}, @dots{})
@deftypefnx {} {@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 nonzero, "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 axes,
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.

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


@c quiver scripts/plot/draw/quiver.m
@anchor{XREFquiver}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} quiver (@var{u}, @var{v})
@deftypefnx {} {} quiver (@var{x}, @var{y}, @var{u}, @var{v})
@deftypefnx {} {} quiver (@dots{}, @var{s})
@deftypefnx {} {} quiver (@dots{}, @var{style})
@deftypefnx {} {} quiver (@dots{}, "filled")
@deftypefnx {} {} quiver (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} quiver (@dots{})

Plot a 2-D vector field with arrows.

Plot the (@var{u}, @var{v}) components of a vector field at the grid points
defined by (@var{x}, @var{y}).  If the grid is uniform then @var{x} and
@var{y} can be specified as grid vectors and @code{meshgrid} is used to
create the 2-D grid.

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

The optional input @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 1.0 will
result in the longest vector exactly filling one grid square.  A value of 0
or @qcode{"off"} 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 the markers are drawn at the origin of the vectors (which are the grid
points defined by @var{x} and @var{y}).  When a marker is specified, the
arrowhead is not drawn.  If the argument @qcode{"filled"} is given then the
markers are filled.  If name-value plot style properties are used, they must
appear in pairs and follow any other plot style arguments.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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

@xseealso{@ref{XREFquiver3,,quiver3}, @ref{XREFcompass,,compass}, @ref{XREFfeather,,feather}, @ref{XREFplot,,plot}}
@end deftypefn


@c quiver3 scripts/plot/draw/quiver3.m
@anchor{XREFquiver3}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} quiver3 (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w})
@deftypefnx {} {} quiver3 (@var{z}, @var{u}, @var{v}, @var{w})
@deftypefnx {} {} quiver3 (@dots{}, @var{s})
@deftypefnx {} {} quiver3 (@dots{}, @var{style})
@deftypefnx {} {} quiver3 (@dots{}, "filled")
@deftypefnx {} {} quiver3 (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} quiver3 (@dots{})

Plot a 3-D vector field with arrows.

Plot the (@var{u}, @var{v}, @var{w}) components of a vector field at the
grid points defined by (@var{x}, @var{y}, @var{z}).  If the grid is uniform
then @var{x}, @var{y}, and @var{z} can be specified as grid vectors and
@code{meshgrid} is used to create the 3-D grid.

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

The optional input @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 1.0 will
result in the longest vector exactly filling one grid cube.  A value of 0
or @qcode{"off"} 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 the markers are drawn at the origin of the vectors (which are the grid
points defined by @var{x}, @var{y}, @var{z}).  When a marker is specified,
the arrowhead is not drawn.  If the argument @qcode{"filled"} is given then
the markers are filled.  If name-value plot style properties are used, they
must appear in pairs and follow any other plot style arguments.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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

@xseealso{@ref{XREFquiver,,quiver}, @ref{XREFcompass,,compass}, @ref{XREFfeather,,feather}, @ref{XREFplot,,plot}}
@end deftypefn


@c streamribbon scripts/plot/draw/streamribbon.m
@anchor{XREFstreamribbon}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} streamribbon (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} streamribbon (@var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} streamribbon (@var{xyz}, @var{x}, @var{y}, @var{z}, @var{anlr_spd}, @var{lin_spd})
@deftypefnx {} {} streamribbon (@var{xyz}, @var{anlr_spd}, @var{lin_spd})
@deftypefnx {} {} streamribbon (@var{xyz}, @var{anlr_rot})
@deftypefnx {} {} streamribbon (@dots{}, @var{width})
@deftypefnx {} {} streamribbon (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} streamribbon (@dots{})
Calculate and display streamribbons.

The streamribbon is constructed by rotating a normal vector around a
streamline according to the angular rotation of the vector field.

The vector field is given by @code{[@var{u}, @var{v}, @var{w}]} and is
defined over a rectangular grid given by @code{[@var{x}, @var{y}, @var{z}]}.
The streamribbons start at the seed points
@code{[@var{sx}, @var{sy}, @var{sz}]}.

@code{streamribbon} can be called with a cell array that contains
pre-computed streamline data.  To do this, @var{xyz} must be created with
the @code{stream3} function.  @var{lin_spd} is the linear speed of the
vector field and can be calculated from @code{[@var{u}, @var{v}, @var{w}]}
by the square root of the sum of the squares.  The angular speed
@var{anlr_spd} is the projection of the angular velocity onto the velocity
of the normalized vector field and can be calculated with the @code{curl}
command.  This option is useful if you need to alter the integrator step
size or the maximum number of streamline vertices.

Alternatively, ribbons can be created from an array of vertices @var{xyz} of
a path curve.  @var{anlr_rot} contains the angles of rotation around the
edges between adjacent vertices of the path curve.

The input parameter @var{width} sets the width of the streamribbons.

Streamribbons are colored according to the total angle of rotation along the
ribbon.

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

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

Example:

@example
@group
[x, y, z] = meshgrid (0:0.2:4, -1:0.2:1, -1:0.2:1);
u = - x + 10;
v = 10 * z.*x;
w = - 10 * y.*x;
streamribbon (x, y, z, u, v, w, [0, 0], [0, 0.6], [0, 0]);
view (3);
@end group
@end example

@xseealso{@ref{XREFstreamline,,streamline}, @ref{XREFstream3,,stream3}, @ref{XREFstreamtube,,streamtube}, @ref{XREFostreamtube,,ostreamtube}}

@end deftypefn


@c streamtube scripts/plot/draw/streamtube.m
@anchor{XREFstreamtube}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} streamtube (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} streamtube (@var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} streamtube (@var{xyz}, @var{x}, @var{y}, @var{z}, @var{div})
@deftypefnx {} {} streamtube (@var{xyz}, @var{div})
@deftypefnx {} {} streamtube (@var{xyz}, @var{dia})
@deftypefnx {} {} streamtube (@dots{}, @var{options})
@deftypefnx {} {} streamtube (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} streamtube (@dots{})
Plot tubes scaled by the divergence along streamlines.

@code{streamtube} draws tubes whose diameter is scaled by the divergence of
a vector field.  The vector field is given by
@code{[@var{u}, @var{v}, @var{w}]} and is defined over a rectangular grid
given by @code{[@var{x}, @var{y}, @var{z}]}.  The tubes start at the
seed points @code{[@var{sx}, @var{sy}, @var{sz}]} and are plot along
streamlines.

@code{streamtube} can also be called with a cell array containing
pre-computed streamline data.  To do this, @var{xyz} must be created with
the @code{stream3} command.  @var{div} is used to scale the tubes.
In order to plot tubes scaled by the vector field divergence, @var{div}
must be calculated with the @code{divergence} command.

A tube diameter of zero corresponds to the smallest scaling value along the
streamline and the largest tube diameter corresponds to the largest scaling
value.

It is also possible to draw a tube along an arbitrary array of vertices
@var{xyz}.  The tube diameter can be specified by the vertex array @var{dia}
or by a constant.

The input parameter @var{options} is a 2-D vector of the form
@code{[@var{scale}, @var{n}]}.  The first parameter scales the tube
diameter (default 1).  The second parameter specifies the number of vertices
that are used to construct the tube circumference (default 20).

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

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

@xseealso{@ref{XREFstream3,,stream3}, @ref{XREFstreamline,,streamline}, @ref{XREFstreamribbon,,streamribbon}, @ref{XREFostreamtube,,ostreamtube}}
@end deftypefn


@c ostreamtube scripts/plot/draw/ostreamtube.m
@anchor{XREFostreamtube}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ostreamtube (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} ostreamtube (@var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} ostreamtube (@var{xyz}, @var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w})
@deftypefnx {} {} ostreamtube (@dots{}, @var{options})
@deftypefnx {} {} ostreamtube (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ostreamtube (@dots{})
Calculate and display streamtubes.

Streamtubes are approximated by connecting circular crossflow areas
along a streamline.  The expansion of the flow is determined by the local
crossflow divergence.

The vector field is given by @code{[@var{u}, @var{v}, @var{w}]} and is
defined over a rectangular grid given by @code{[@var{x}, @var{y}, @var{z}]}.
The streamtubes start at the seed points
@code{[@var{sx}, @var{sy}, @var{sz}]}.

The tubes are colored based on the local vector field strength.

The input parameter @var{options} is a 2-D vector of the form
@code{[@var{scale}, @var{n}]}.  The first parameter scales the start radius
of the streamtubes (default 1).  The second parameter specifies the number
of vertices that are used to construct the tube circumference (default 20).

@code{ostreamtube} can be called with a cell array containing pre-computed
streamline data.  To do this, @var{xyz} must be created with the
@code{stream3} function.  This option is useful if you need to alter the
integrator step size or the maximum number of vertices of the streamline.

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

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

Example:

@example
@group
[x, y, z] = meshgrid (-1:0.1:1, -1:0.1:1, -3:0.1:0);
u = -x / 10 - y;
v = x - y / 10;
w = - ones (size (x)) / 10;
ostreamtube (x, y, z, u, v, w, 1, 0, 0);
@end group
@end example

@xseealso{@ref{XREFstream3,,stream3}, @ref{XREFstreamline,,streamline}, @ref{XREFstreamribbon,,streamribbon}, @ref{XREFstreamtube,,streamtube}}
@end deftypefn


@c streamline scripts/plot/draw/streamline.m
@anchor{XREFstreamline}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} streamline (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} streamline (@var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} streamline (@dots{}, @var{options})
@deftypefnx {} {} streamline (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} streamline (@dots{})
Plot streamlines of 2-D or 3-D vector fields.

Plot streamlines of a 2-D or 3-D vector field given by
@code{[@var{u}, @var{v}]} or @code{[@var{u}, @var{v}, @var{w}]}.  The vector
field is defined over a rectangular grid given by @code{[@var{x}, @var{y}]}
or @code{[@var{x}, @var{y}, @var{z}]}.  The streamlines start at the seed
points @code{[@var{sx}, @var{sy}]} or @code{[@var{sx}, @var{sy}, @var{sz}]}.

The input parameter @var{options} is a 2-D vector of the form
@code{[@var{stepsize}, @var{max_vertices}]}.  The first parameter
specifies the step size used for trajectory integration (default 0.1).  A
negative value is allowed which will reverse the direction of integration.
The second parameter specifies the maximum number of segments used to
create a streamline (default 10,000).

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

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

Example:

@example
@group
[x, y] = meshgrid (-1.5:0.2:2, -1:0.2:2);
u = - x / 4 - y;
v = x - y / 4;
streamline (x, y, u, v, 1.7, 1.5);
@end group
@end example

@xseealso{@ref{XREFstream2,,stream2}, @ref{XREFstream3,,stream3}, @ref{XREFstreamribbon,,streamribbon}, @ref{XREFstreamtube,,streamtube}, @ref{XREFostreamtube,,ostreamtube}}
@end deftypefn


@c stream2 scripts/plot/draw/stream2.m
@anchor{XREFstream2}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{xy} =} stream2 (@var{x}, @var{y}, @var{u}, @var{v}, @var{sx}, @var{sy})
@deftypefnx {} {@var{xy} =} stream2 (@var{u}, @var{v}, @var{sx}, @var{sy})
@deftypefnx {} {@var{xy} =} stream2 (@dots{}, @var{options})
Compute 2-D streamline data.

Calculates streamlines of a vector field given by @code{[@var{u}, @var{v}]}.
The vector field is defined over a rectangular grid given by
@code{[@var{x}, @var{y}]}.  The streamlines start at the seed points
@code{[@var{sx}, @var{sy}]}.  The returned value @var{xy} contains a cell
array of vertex arrays.  If the starting point is outside the vector field,
@code{[]} is returned.

The input parameter @var{options} is a 2-D vector of the form
@code{[@var{stepsize}, @var{max_vertices}]}.  The first parameter
specifies the step size used for trajectory integration (default 0.1).  A
negative value is allowed which will reverse the direction of integration.
The second parameter specifies the maximum number of segments used to
create a streamline (default 10,000).

The return value @var{xy} is a @nospell{nverts x 2} matrix containing the
coordinates of the field line segments.

Example:

@example
@group
[x, y] = meshgrid (0:3);
u = 2 * x;
v = y;
xy = stream2 (x, y, u, v, 1.0, 0.5);
@end group
@end example

@xseealso{@ref{XREFstreamline,,streamline}, @ref{XREFstream3,,stream3}}
@end deftypefn


@c stream3 scripts/plot/draw/stream3.m
@anchor{XREFstream3}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{xyz} =} stream3 (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {@var{xyz} =} stream3 (@var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {@var{xyz} =} stream3 (@dots{}, @var{options})
Compute 3-D streamline data.

Calculate streamlines of a vector field given by @code{[@var{u}, @var{v},
@var{w}]}.  The vector field is defined over a rectangular grid given by
@code{[@var{x}, @var{y}, @var{z}]}.  The streamlines start at the seed
points @code{[@var{sx}, @var{sy}, @var{sz}]}.  The returned value @var{xyz}
contains a cell array of vertex arrays.  If the starting point is outside
the vector field, @code{[]} is returned.

The input parameter @var{options} is a 2-D vector of the form
@code{[@var{stepsize}, @var{max_vertices}]}.  The first parameter
specifies the step size used for trajectory integration (default 0.1).  A
negative value is allowed which will reverse the direction of integration.
The second parameter specifies the maximum number of segments used to
create a streamline (default 10,000).

The return value @var{xyz} is a @nospell{nverts x 3} matrix containing the
coordinates of the field line segments.

Example:

@example
@group
[x, y, z] = meshgrid (0:3);
u = 2 * x;
v = y;
w = 3 * z;
xyz = stream3 (x, y, z, u, v, w, 1.0, 0.5, 0.0);
@end group
@end example

@xseealso{@ref{XREFstream2,,stream2}, @ref{XREFstreamline,,streamline}, @ref{XREFstreamribbon,,streamribbon}, @ref{XREFstreamtube,,streamtube}, @ref{XREFostreamtube,,ostreamtube}}
@end deftypefn


@c compass scripts/plot/draw/compass.m
@anchor{XREFcompass}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} compass (@var{u}, @var{v})
@deftypefnx {} {} compass (@var{z})
@deftypefnx {} {} compass (@dots{}, @var{style})
@deftypefnx {} {} compass (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} feather (@var{u}, @var{v})
@deftypefnx {} {} feather (@var{z})
@deftypefnx {} {} feather (@dots{}, @var{style})
@deftypefnx {} {} feather (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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

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


@c pcolor scripts/plot/draw/pcolor.m
@anchor{XREFpcolor}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} pcolor (@var{x}, @var{y}, @var{c})
@deftypefnx {} {} pcolor (@var{c})
@deftypefnx {} {} pcolor (@var{hax}, @dots{})
@deftypefnx {} {@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{clim}, 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 axes,
rather than the current axes returned by @code{gca}.

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

@xseealso{@ref{XREFclim,,clim}, @ref{XREFshading,,shading}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFcontour,,contour}, @ref{XREFimagesc,,imagesc}}
@end deftypefn


@c area scripts/plot/draw/area.m
@anchor{XREFarea}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} area (@var{y})
@deftypefnx {} {} area (@var{x}, @var{y})
@deftypefnx {} {} area (@dots{}, @var{lvl})
@deftypefnx {} {} area (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} area (@var{hax}, @dots{})
@deftypefnx {} {@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.  The full list of properties is documented at
@ref{Patch Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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
@xseealso{@ref{XREFplot,,plot}, @ref{XREFpatch,,patch}}
@end deftypefn


@c fill scripts/plot/draw/fill.m
@anchor{XREFfill}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} fill (@var{x}, @var{y}, @var{c})
@deftypefnx {} {} fill (@var{x1}, @var{y1}, @var{c1}, @var{x2}, @var{y2}, @var{c2})
@deftypefnx {} {} fill (@dots{}, @var{prop}, @var{val})
@deftypefnx {} {} fill (@var{hax}, @dots{})
@deftypefnx {} {@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{clim} 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.  The full list of properties is
documented at @ref{Patch Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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

@xseealso{@ref{XREFpatch,,patch}, @ref{XREFfill3,,fill3}, @ref{XREFclim,,clim}, @ref{XREFcolormap,,colormap}}
@end deftypefn


@c fill3 scripts/plot/draw/fill3.m
@anchor{XREFfill3}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} fill3 (@var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {} {} fill3 (@var{x1}, @var{y1}, @var{z1}, @var{c1}, @var{x2}, @var{y2}, @var{z2}, @var{c2})
@deftypefnx {} {} fill3 (@dots{}, @var{prop}, @var{val})
@deftypefnx {} {} fill3 (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} fill3 (@dots{})
Create one or more filled 3-D polygons.

The inputs @var{x}, @var{y}, and @var{z} 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{fill3} 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{clim} and then indexed into the current colormap.  A row vector will
color each polygon (a column from matrices @var{x}, @var{y}, and @var{z})
with a single computed color.  A matrix @var{c} of the same size as @var{x},
@var{y}, and @var{z} 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.  The full list of properties is
documented at @ref{Patch Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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: oblique red rectangle

@example
@group
vertices = [0 0 0
            1 1 0
            1 1 1
            0 0 1];
fill3 (vertices(:,1), vertices(:,2), vertices(:,3), "r");
axis ([-0.5 1.5, -0.5 1.5, -0.5 1.5]);
axis ("equal");
grid ("on");
view (-80, 25);
@end group
@end example

@xseealso{@ref{XREFpatch,,patch}, @ref{XREFfill,,fill}, @ref{XREFclim,,clim}, @ref{XREFcolormap,,colormap}}
@end deftypefn


@c comet scripts/plot/draw/comet.m
@anchor{XREFcomet}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} comet (@var{y})
@deftypefnx {} {} comet (@var{x}, @var{y})
@deftypefnx {} {} comet (@var{x}, @var{y}, @var{p})
@deftypefnx {} {} 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 @code{5 / numel (@var{y})}.

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


@c comet3 scripts/plot/draw/comet3.m
@anchor{XREFcomet3}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} comet3 (@var{z})
@deftypefnx {} {} comet3 (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} comet3 (@var{x}, @var{y}, @var{z}, @var{p})
@deftypefnx {} {} 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 @code{5 / numel (@var{z})}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.
@xseealso{@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.  By default, high level plotting functions such as
@code{plot} reset axes properties.  Any customization of properties, for
example by calling @code{axis}, @code{xlim}, etc., should happen after the plot
is done or, alternatively, after calling the @ref{XREFhold, ,hold function}.

@c axis scripts/plot/appearance/axis.m
@anchor{XREFaxis}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} axis ()
@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi}])
@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi} @var{y_lo} @var{y_hi}])
@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi} @var{y_lo} @var{y_hi} @var{z_lo} @var{z_hi}])
@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi} @var{y_lo} @var{y_hi} @var{z_lo} @var{z_hi} @var{c_lo} @var{c_hi}])
@deftypefnx {} {} axis (@var{option})
@deftypefnx {} {} axis (@var{option1}, @var{option2}, @dots{})
@deftypefnx {} {} axis (@var{hax}, @dots{})
@deftypefnx {} {@var{limits} =} axis ()
Set axis limits and appearance.

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

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.

The following options control the aspect ratio of the axes.

@table @asis
@item @qcode{"equal"}
Force x-axis unit distance to equal y-axis (and z-axis) unit distance.

@item @qcode{"square"}
Force a square axis aspect ratio.

@item @nospell{@qcode{"vis3d"}}
Set aspect ratio modes (@qcode{"DataAspectRatio"},
@qcode{"PlotBoxAspectRatio"}) to @qcode{"manual"} for rotation without
stretching.

@item  @qcode{"normal"}
@itemx @qcode{"fill"}
Restore default automatically computed aspect ratios.
@end table

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

@table @asis
@item  @qcode{"auto"}
@itemx @qcode{"auto[xyz]"}
@itemx @qcode{"auto [xyz]"}
Set nice auto-computed limits around the data for all axes, or only
the specified axes.

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

@item @qcode{"tickaligned"}
Fix axes to the limits of the closest ticks.

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

@item @qcode{"padded"}
Fix axes to the limits of the data plus margins of about 7% of the
data extent.

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

@end table

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

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

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

@item @qcode{"nolabel"}
Turn tick labels off for all axes.
@end table

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

@table @asis
@item @qcode{"xy"}
Default y-axis, larger values are near the top.

@item @qcode{"ij"}
Reverse y-axis, smaller values are near the top.
@end table

@noindent
The following options affects the visibility of the axes.

@table @asis
@item @qcode{"on"}
Make the axes visible.

@item @qcode{"off"}
Hide the axes.
@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}.

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

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

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

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

@xseealso{@ref{XREFxlim,,xlim}, @ref{XREFylim,,ylim}, @ref{XREFzlim,,zlim}, @ref{XREFclim,,clim}, @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 @code{clim}
function.

@c clim scripts/plot/appearance/clim.m
@anchor{XREFclim}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} clim ([cmin cmax])
@deftypefnx {} {} clim ("auto")
@deftypefnx {} {} clim ("manual")
@deftypefnx {} {} clim (@var{hax}, @dots{})
@deftypefnx {} {@var{limits} =} clim ()
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 axes rather than the current axes returned by @code{gca}.

Called without arguments the current color axis limits are returned.

Programming Note: The color axis affects the display of image, patch, and
surface graphics objects, but @strong{only} if the @qcode{"cdata"} property
has indexed data and the @qcode{"cdatamapping"} property is set to
@qcode{"scaled"}.  Graphic objects with true color @code{cdata}, or
@qcode{"direct"} @code{cdatamapping} are not affected.
@xseealso{@ref{XREFcolormap,,colormap}, @ref{XREFaxis,,axis}}
@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 xlim scripts/plot/appearance/xlim.m
@anchor{XREFxlim}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{xlimits} =} xlim ()
@deftypefnx {} {@var{xmode} =} xlim ("mode")
@deftypefnx {} {@var{xmethod} =} xlim ("method")
@deftypefnx {} {} xlim ([@var{x_lo} @var{x_hi}])
@deftypefnx {} {} xlim ("mode")
@deftypefnx {} {} xlim ("method")
@deftypefnx {} {} 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"}.

With the input query @qcode{"method"}, return the current x-limit
calculation method which is either @qcode{"tickaligned"}, @qcode{"tight"},
or @qcode{"padded"}.

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 special values -Inf and Inf can be used to indicate that either
the lower axis limit or upper axis limit should be automatically calculated.

The current limit calculation @qcode{"mode"} may be one of

@table @asis
@item @qcode{"auto"} (default)
Automatically calculate limits based on the plot data and the currently
specified limit calculation method.

@item @qcode{"manual"}
Fix axis limits at current values.
@end table

The current limit calculation method may be one of

@table @asis
@item @qcode{"tickaligned"} (default)
Calculate limits that encompass all of the data and extend outwards to the
nearest tick mark.

@item @qcode{"tight"}
Calculate limits that exactly fit the data range.

@item @qcode{"padded"}
Calculate limits that leave a margin around the data of approximately 7% of
the data range.
@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}.

Programming Note: The @code{xlim} function operates by modifying the
@qcode{"xlim"}, @qcode{"xlimmode"}, and @qcode{"xlimitmethod"} properties of
an axes object.  These properties can be directly inspected and altered with
@code{get}/@code{set}.
@xseealso{@ref{XREFylim,,ylim}, @ref{XREFzlim,,zlim}, @ref{XREFaxis,,axis}, @ref{XREFset,,set}, @ref{XREFget,,get}, @ref{XREFgca,,gca}}
@end deftypefn


@c ylim scripts/plot/appearance/ylim.m
@anchor{XREFylim}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{ylimits} =} ylim ()
@deftypefnx {} {@var{ymode} =} ylim ("mode")
@deftypefnx {} {@var{ymethod} =} ylim ("method")
@deftypefnx {} {} ylim ([@var{y_lo} @var{y_hi}])
@deftypefnx {} {} ylim ("mode")
@deftypefnx {} {} ylim ("method")
@deftypefnx {} {} ylim (@var{hax}, @dots{})
Query or set the limits of the y-axis for the current plot.

Called without arguments @code{ylim} returns the y-axis limits of the
current plot.

With the input query @qcode{"mode"}, return the current y-limit calculation
mode which is either @qcode{"auto"} or @qcode{"manual"}.

With the input query @qcode{"method"}, return the current y-limit
calculation method which is either @qcode{"tickaligned"}, @qcode{"tight"},
or @qcode{"padded"}.

If passed a 2-element vector [@var{y_lo} @var{y_hi}], the limits of the
y-axis are set to these values and the mode is set to @qcode{"manual"}.
The special values -Inf and Inf can be used to indicate that either
the lower axis limit or upper axis limit should be automatically calculated.

The current limit calculation @qcode{"mode"} may be one of

@table @asis
@item @qcode{"auto"} (default)
Automatically calculate limits based on the plot data and the currently
specified limit calculation method.

@item @qcode{"manual"}
Fix axis limits at current values.
@end table

The current limit calculation method may be one of

@table @asis
@item @qcode{"tickaligned"} (default)
Calculate limits that encompass all of the data and extend outwards to the
nearest tick mark.

@item @qcode{"tight"}
Calculate limits that exactly fit the data range.

@item @qcode{"padded"}
Calculate limits that leave a margin around the data of approximately 7% of
the data range.
@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}.

Programming Note: The @code{ylim} function operates by modifying the
@qcode{"ylim"}, @qcode{"ylimmode"}, and @qcode{"ylimitmethod"} properties of
an axes object.  These properties can be directly inspected and altered with
@code{get}/@code{set}.
@xseealso{@ref{XREFxlim,,xlim}, @ref{XREFzlim,,zlim}, @ref{XREFaxis,,axis}, @ref{XREFset,,set}, @ref{XREFget,,get}, @ref{XREFgca,,gca}}
@end deftypefn


@c zlim scripts/plot/appearance/zlim.m
@anchor{XREFzlim}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{zlimits} =} zlim ()
@deftypefnx {} {@var{zmode} =} zlim ("mode")
@deftypefnx {} {@var{zmethod} =} zlim ("method")
@deftypefnx {} {} zlim ([@var{z_lo} @var{z_hi}])
@deftypefnx {} {} zlim ("mode")
@deftypefnx {} {} zlim ("method")
@deftypefnx {} {} zlim (@var{hax}, @dots{})
Query or set the limits of the z-axis for the current plot.

Called without arguments @code{zlim} returns the z-axis limits of the
current plot.

With the input query @qcode{"mode"}, return the current z-limit calculation
mode which is either @qcode{"auto"} or @qcode{"manual"}.

With the input query @qcode{"method"}, return the current z-limit
calculation method which is either @qcode{"tickaligned"}, @qcode{"tight"},
or @qcode{"padded"}.

If passed a 2-element vector [@var{z_lo} @var{z_hi}], the limits of the
z-axis are set to these values and the mode is set to @qcode{"manual"}.
The special values -Inf and Inf can be used to indicate that either
the lower axis limit or upper axis limit should be automatically calculated.

The current limit calculation @qcode{"mode"} may be one of

@table @asis
@item @qcode{"auto"} (default)
Automatically calculate limits based on the plot data and the currently
specified limit calculation method.

@item @qcode{"manual"}
Fix axis limits at current values.
@end table

The current limit calculation method may be one of

@table @asis
@item @qcode{"tickaligned"} (default)
Calculate limits that encompass all of the data and extend outwards to the
nearest tick mark.

@item @qcode{"tight"}
Calculate limits that exactly fit the data range.

@item @qcode{"padded"}
Calculate limits that leave a margin around the data of approximately 7% of
the data range.
@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}.

Programming Note: The @code{zlim} function operates by modifying the
@qcode{"zlim"}, @qcode{"zlimmode"}, and @qcode{"zlimitmethod"} properties of
an axes object.  These properties can be directly inspected and altered with
@code{get}/@code{set}.
@xseealso{@ref{XREFxlim,,xlim}, @ref{XREFylim,,ylim}, @ref{XREFaxis,,axis}, @ref{XREFset,,set}, @ref{XREFget,,get}, @ref{XREFgca,,gca}}
@end deftypefn


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

@c FIXME: Update this section if polarplot and polar axes changes change the
@c        associated axis properties.
@c xticks scripts/plot/appearance/xticks.m
@anchor{XREFxticks}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tickval} =} xticks
@deftypefnx {} {@var{mode} =} xticks ("mode")
@deftypefnx {} {} xticks (@var{tickval})
@deftypefnx {} {} xticks ("auto")
@deftypefnx {} {} xticks ("manual")
@deftypefnx {} {@dots{} =} xticks (@var{hax}, @dots{})
Query or set the tick values on the x-axis of the current axis.

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

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

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

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

@xseealso{@ref{XREFxticklabels,,xticklabels}, @ref{XREFyticks,,yticks}, @ref{XREFzticks,,zticks}, @ref{XREFrticks,,rticks}, @ref{XREFthetaticks,,thetaticks}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c yticks scripts/plot/appearance/yticks.m
@anchor{XREFyticks}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tickval} =} yticks
@deftypefnx {} {@var{mode} =} yticks ("mode")
@deftypefnx {} {} yticks (@var{tickval})
@deftypefnx {} {} yticks ("auto")
@deftypefnx {} {} yticks ("manual")
@deftypefnx {} {@dots{} =} yticks (@var{hax}, @dots{})
Query or set the tick values on the y-axis of the current axis.

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

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

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

Requesting a return value when calling @code{yticks} to set a property value
will result in an error.

@xseealso{@ref{XREFyticklabels,,yticklabels}, @ref{XREFxticks,,xticks}, @ref{XREFzticks,,zticks}, @ref{XREFrticks,,rticks}, @ref{XREFthetaticks,,thetaticks}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c zticks scripts/plot/appearance/zticks.m
@anchor{XREFzticks}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tickval} =} zticks
@deftypefnx {} {@var{mode} =} zticks ("mode")
@deftypefnx {} {} zticks (@var{tickval})
@deftypefnx {} {} zticks ("auto")
@deftypefnx {} {} zticks ("manual")
@deftypefnx {} {@dots{} =} zticks (@var{hax}, @dots{})
Query or set the tick values on the z-axis of the current axis.

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

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

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

Requesting a return value when calling @code{zticks} to set a property value
will result in an error.

@xseealso{@ref{XREFzticklabels,,zticklabels}, @ref{XREFxticks,,xticks}, @ref{XREFyticks,,yticks}, @ref{XREFrticks,,rticks}, @ref{XREFthetaticks,,thetaticks}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c rticks scripts/plot/appearance/rticks.m
@anchor{XREFrticks}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tickval} =} rticks
@deftypefnx {} {} rticks (@var{tickval})
@deftypefnx {} {@dots{} =} rticks (@var{hax}, @dots{})
Query or set the tick values on the r-axis of the current axis.

When called without argument, return the current tick locations as specified
in the @qcode{"rtick"} axes property.  These locations can be changed by
calling @code{rticks} with a vector of tick values.  Note: ascending order
is not required.

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

Requesting a return value when calling @code{rticks} to set a property value
will result in an error.

NOTE: Octave does not currently implement polaraxes objects.  It is
therefore not possible to query or set a @qcode{"mode"} for the
@qcode{"rtick"} property as can be done with the equivalent functions for
@var{x}, @var{y}, and @var{z} axes.

@xseealso{@ref{XREFthetaticks,,thetaticks}, @ref{XREFxticks,,xticks}, @ref{XREFyticks,,yticks}, @ref{XREFzticks,,zticks}, @ref{XREFpolar,,polar}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c thetaticks scripts/plot/appearance/thetaticks.m
@anchor{XREFthetaticks}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tickval} =} thetaticks
@deftypefnx {} {} thetaticks (@var{tickval})
@deftypefnx {} {@dots{} =} thetaticks (@var{hax}, @dots{})
Query or set the tick values on the theta-axis of the current axis.

When called without argument, return the current tick locations as specified
in the @qcode{"ttick"} axes property.  These locations can be changed by
calling @code{thetaticks} with a vector of tick values.  Note: ascending
order is not required.

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

Requesting a return value when calling @code{thetaticks} to set a property
value will result in an error.

NOTE: Octave does not currently implement polaraxes objects.  It is
therefore not possible to query or set a @qcode{"mode"} for the
@qcode{"thetatick"} property as can be done with the equivalent functions
for @var{x}, @var{y}, and @var{z} axes.

@xseealso{@ref{XREFrticks,,rticks}, @ref{XREFxticks,,xticks}, @ref{XREFyticks,,yticks}, @ref{XREFzticks,,zticks}, @ref{XREFpolar,,polar}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


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

@c FIXME: Update this section if polarplot and polar axes changes the
@c        associated axis properties.
@c        Matlab also implements rticklabels and thetaticklabels.
@c xticklabels scripts/plot/appearance/xticklabels.m
@anchor{XREFxticklabels}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{labels} =} xticklabels
@deftypefnx {} {@var{mode} =} xticklabels ("mode")
@deftypefnx {} {} xticklabels (@var{tickval})
@deftypefnx {} {} xticklabels ("auto")
@deftypefnx {} {} xticklabels ("manual")
@deftypefnx {} {@dots{} =} xticklabels (@var{hax}, @dots{})
Query or set the tick labels on the x-axis of the current axis.

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

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

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

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

@xseealso{@ref{XREFxticks,,xticks}, @ref{XREFyticklabels,,yticklabels}, @ref{XREFzticklabels,,zticklabels}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c yticklabels scripts/plot/appearance/yticklabels.m
@anchor{XREFyticklabels}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{labels} =} yticklabels
@deftypefnx {} {@var{mode} =} yticklabels ("mode")
@deftypefnx {} {} yticklabels (@var{tickval})
@deftypefnx {} {} yticklabels ("auto")
@deftypefnx {} {} yticklabels ("manual")
@deftypefnx {} {@dots{} =} yticklabels (@var{hax}, @dots{})
Query or set the tick labels on the x-axis of the current axis.

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

When called with argument @qcode{"mode"}, @code{yticklabels} returns the
current value of the axes property @qcode{"yticklabelmode"}.  This property
can be changed by calling @code{yticklabels} with either @qcode{"auto"}
(algorithm determines tick labels) or @qcode{"manual"} (tick labels remain
fixed).  Note: Specifying yticklabel values will also set the
@qcode{"yticklabelmode"} and @qcode{"yticks"} properties to
@qcode{"manual"}.

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

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

@xseealso{@ref{XREFyticks,,yticks}, @ref{XREFxticklabels,,xticklabels}, @ref{XREFzticklabels,,zticklabels}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c zticklabels scripts/plot/appearance/zticklabels.m
@anchor{XREFzticklabels}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{labels} =} zticklabels
@deftypefnx {} {@var{mode} =} zticklabels ("mode")
@deftypefnx {} {} zticklabels (@var{tickval})
@deftypefnx {} {} zticklabels ("auto")
@deftypefnx {} {} zticklabels ("manual")
@deftypefnx {} {@dots{} =} zticklabels (@var{hax}, @dots{})
Query or set the tick labels on the x-axis of the current axis.

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

When called with argument @qcode{"mode"}, @code{zticklabels} returns the
current value of the axes property @qcode{"zticklabelmode"}.  This property
can be changed by calling @code{zticklabels} with either @qcode{"auto"}
(algorithm determines tick labels) or @qcode{"manual"} (tick labels remain
fixed).  Note: Specifying zticklabel values will also set the
@qcode{"zticklabelmode"} and @qcode{"zticks"} properties to
@qcode{"manual"}.

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

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

@xseealso{@ref{XREFzticks,,zticks}, @ref{XREFxticklabels,,xticklabels}, @ref{XREFzticklabels,,zticklabels}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c rticklabels scripts/plot/appearance/rticklabels.m
@anchor{XREFrticklabels}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{labels} =} rticklabels
@deftypefnx {} {} rticklabels (@var{tickval})
@deftypefnx {} {@dots{} =} rticklabels (@var{hax}, @dots{})
Query or set the tick labels on the r-axis of a polar plot.

When called without an argument, return a cell array of strings of the
current rtick labels.

When called with the argument @var{tickval} being a vector of numbers or
a cell array of strings and/or numbers, the labels will be changed to
match these new values.  Note that the center point of the plots made by
@code{polar} are never labeled, so the first specified label will be
applied to the second rtick location and subesquent labels will progress
outward.

If fewer labels are specified than the current number of tick marks, those
labels will be applied starting with the innermost tick labels, and blank
labels will be appended to the remainder.  If the specified label count
exceeds the number of tick labels, the excess labels are ignored.

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

Requesting a return value when calling @code{rticklabels} to set a property
value will result in an error.

Compatability Note: The @qcode{'mode'} property for rticklabels has not yet
been implemented.

@xseealso{@ref{XREFpolar,,polar}, @ref{XREFrticks,,rticks}, @ref{XREFthetaticklabels,,thetaticklabels}, @ref{XREFxticklabels,,xticklabels}, @ref{XREFyticklabels,,yticklabels}, @ref{XREFzticklabels,,zticklabels}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c thetaticklabels scripts/plot/appearance/thetaticklabels.m
@anchor{XREFthetaticklabels}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{labels} =} thetaticklabels
@deftypefnx {} {} thetaticklabels (@var{tickval})
@deftypefnx {} {@dots{} =} thetaticklabels (@var{hax}, @dots{})
Query or set the tick labels on the theta-axis of a polar plot.

When called without an argument, return a cell array of strings of the
current ttick labels.

When called with the argument @var{tickval} being a vector of numbers or
a cell array of strings and/or numbers, the labels will be changed to
match these new values.  Values will be applied starting with the
zero-degree tick mark and will progress counterclockwise.

If fewer labels are specified than the current number of theta tick marks,
those labels will be applied starting at the zero-degree tick mark and
blank labels will be appended to the remainder.  If the specified label
count exceeds the number of tick labels, the excess labels are ignored.

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

Requesting a return value when calling @code{thetaticklabels} to set a
property value will result in an error.

Compatability Note: The @qcode{'mode'} property for thetaticklabels has not
yet been implemented.

@xseealso{@ref{XREFpolar,,polar}, @ref{XREFthetaticks,,thetaticks}, @ref{XREFrticklabels,,rticklabels}, @ref{XREFxticklabels,,xticklabels}, @ref{XREFyticklabels,,yticklabels}, @ref{XREFzticklabels,,zticklabels}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


The @code{xtickangle}, @code{ytickangle}, and @code{ztickangle} functions
may be used to get or set the rotation angle of labels for the respective axis.
Each has the same form.

@c xtickangle scripts/plot/appearance/xtickangle.m
@anchor{XREFxtickangle}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{angle} =} xtickangle ()
@deftypefnx {} {@var{angle} =} xtickangle (@var{hax})
@deftypefnx {} {} xtickangle (@var{angle})
@deftypefnx {} {} xtickangle (@var{hax}, @var{angle})
Query or set the rotation angle of the tick labels on the x-axis of the
current axes.

When called without an argument, return the rotation angle in degrees of the
tick labels as specified in the axes property @qcode{"XTickLabelRotation"}.
When called with a numeric scalar @var{angle}, rotate the tick labels
counterclockwise to @var{angle} degrees.

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

Programming Notes:
@enumerate
@item
The @qcode{"XTickLabelRotation"} property is currently unimplemented in
Octave.  The property can be set and queried, but has no effect on the plot.

@item
Requesting a return value while also setting a specified
rotation will result in an error.
@end enumerate

@xseealso{@ref{XREFytickangle,,ytickangle}, @ref{XREFztickangle,,ztickangle}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c ytickangle scripts/plot/appearance/ytickangle.m
@anchor{XREFytickangle}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{angle} =} ytickangle ()
@deftypefnx {} {@var{angle} =} ytickangle (@var{hax})
@deftypefnx {} {} ytickangle (@var{angle})
@deftypefnx {} {} ytickangle (@var{hax}, @var{angle})
Query or set the rotation angle of the tick labels on the y-axis of the
current axes.

When called without an argument, return the rotation angle in degrees of the
tick labels as specified in the axes property @qcode{"YTickLabelRotation"}.
When called with a numeric scalar @var{angle}, rotate the tick labels
counterclockwise to @var{angle} degrees.

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

Programming Notes:
@enumerate
@item
The @qcode{"YTickLabelRotation"} property is currently unimplemented in
Octave.  The property can be set and queried, but has no effect on the plot.

@item
Requesting a return value while also setting a specified
rotation will result in an error.
@end enumerate

@xseealso{@ref{XREFxtickangle,,xtickangle}, @ref{XREFztickangle,,ztickangle}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c ztickangle scripts/plot/appearance/ztickangle.m
@anchor{XREFztickangle}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{angle} =} ztickangle ()
@deftypefnx {} {@var{angle} =} ztickangle (@var{hax})
@deftypefnx {} {} ztickangle (@var{angle})
@deftypefnx {} {} ztickangle (@var{hax}, @var{angle})
Query or set the rotation angle of the tick labels on the z-axis of the
current axes.

When called without an argument, return the rotation angle in degrees of the
tick labels as specified in the axes property @qcode{"ZTickLabelRotation"}.
When called with a numeric scalar @var{angle}, rotate the tick labels
counterclockwise to @var{angle} degrees.

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

Programming Notes:
@enumerate
@item
The @qcode{"ZTickLabelRotation"} property is currently unimplemented in
Octave.  The property can be set and queried, but has no effect on the plot.

@item
Requesting a return value while also setting a specified
rotation will result in an error.
@end enumerate

@xseealso{@ref{XREFxtickangle,,xtickangle}, @ref{XREFytickangle,,ytickangle}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@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 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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} fplot (@var{fcn})
@deftypefnx {} {} fplot (@var{fcn}, @var{limits})
@deftypefnx {} {} fplot (@dots{}, @var{tol})
@deftypefnx {} {} fplot (@dots{}, @var{n})
@deftypefnx {} {} fplot (@dots{}, @var{fmt})
@deftypefnx {} {} fplot (@dots{}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} fplot (@var{hax}, @dots{})
@deftypefnx {} {[@var{x}, @var{y}] =} fplot (@dots{})
Plot a function @var{fcn} within the range defined by @var{limits}.

@var{fcn} 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}]}}.  If no limits
are specified the default is @code{[-5, 5]}.

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.

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

The full list of line properties is documented at
@ref{Line Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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

Programming Notes:

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

@code{fplot} performance is better when the function accepts and returns a
vector argument.  Consider this when writing user-defined functions and use
element-by-element operators such as @code{.*}, @code{./}, etc.

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ezplot (@var{f})
@deftypefnx {} {} ezplot (@var{f2v})
@deftypefnx {} {} ezplot (@var{fx}, @var{fy})
@deftypefnx {} {} ezplot (@dots{}, @var{dom})
@deftypefnx {} {} ezplot (@dots{}, @var{n})
@deftypefnx {} {} ezplot (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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.

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ezcontour (@var{f})
@deftypefnx {} {} ezcontour (@dots{}, @var{dom})
@deftypefnx {} {} ezcontour (@dots{}, @var{n})
@deftypefnx {} {} ezcontour (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ezcontourf (@var{f})
@deftypefnx {} {} ezcontourf (@dots{}, @var{dom})
@deftypefnx {} {} ezcontourf (@dots{}, @var{n})
@deftypefnx {} {} ezcontourf (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ezpolar (@var{f})
@deftypefnx {} {} ezpolar (@dots{}, @var{dom})
@deftypefnx {} {} ezpolar (@dots{}, @var{n})
@deftypefnx {} {} ezpolar (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} rectangle ()
@deftypefnx {} {} rectangle (@dots{}, "Position", @var{pos})
@deftypefnx {} {} rectangle (@dots{}, "Curvature", @var{curv})
@deftypefnx {} {} rectangle (@dots{}, "EdgeColor", @var{ec})
@deftypefnx {} {} rectangle (@dots{}, "FaceColor", @var{fc})
@deftypefnx {} {} rectangle (@var{hax}, @dots{})
@deftypefnx {} {@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.
The full list of properties is documented at @ref{Patch Properties}.

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

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


@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);
xlabel ("tx");
ylabel ("ty");
zlabel ("tz");
title ("3-D Sombrero plot");
@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);
xlabel ("r.*sin (t)");
ylabel ("r.*cos (t)");
zlabel ("z");
title ("plot3 display of 3-D helix");
@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} mesh (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} mesh (@var{z})
@deftypefnx {} {} mesh (@dots{}, @var{c})
@deftypefnx {} {} mesh (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} mesh (@var{hax}, @dots{})
@deftypefnx {} {@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{clim} 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.  The full list of properties is documented at
@ref{Surface Properties}.

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

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

@xseealso{@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{XREFclim,,clim}}
@end deftypefn


@c meshc scripts/plot/draw/meshc.m
@anchor{XREFmeshc}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} meshc (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} meshc (@var{z})
@deftypefnx {} {} meshc (@dots{}, @var{c})
@deftypefnx {} {} meshc (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} meshc (@var{hax}, @dots{})
@deftypefnx {} {@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{clim} 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.  The full list of properties is documented at
@ref{Surface Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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.

@xseealso{@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{XREFclim,,clim}}
@end deftypefn


@c meshz scripts/plot/draw/meshz.m
@anchor{XREFmeshz}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} meshz (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} meshz (@var{z})
@deftypefnx {} {} meshz (@dots{}, @var{c})
@deftypefnx {} {} meshz (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} meshz (@var{hax}, @dots{})
@deftypefnx {} {@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{clim} 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.  The full list of properties is documented at
@ref{Surface Properties}.

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

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

@xseealso{@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{XREFclim,,clim}}
@end deftypefn


@c hidden scripts/plot/appearance/hidden.m
@anchor{XREFhidden}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} hidden
@deftypefnx {} {} hidden on
@deftypefnx {} {} hidden off
@deftypefnx {} {@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.

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} surf (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} surf (@var{z})
@deftypefnx {} {} surf (@dots{}, @var{c})
@deftypefnx {} {} surf (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} surf (@var{hax}, @dots{})
@deftypefnx {} {@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{clim} 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.  The full list of properties is documented at
@ref{Surface Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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.
@xseealso{@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{XREFclim,,clim}}
@end deftypefn


@c surfc scripts/plot/draw/surfc.m
@anchor{XREFsurfc}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} surfc (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} surfc (@var{z})
@deftypefnx {} {} surfc (@dots{}, @var{c})
@deftypefnx {} {} surfc (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} surfc (@var{hax}, @dots{})
@deftypefnx {} {@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{clim} 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.  The full list of properties is documented at
@ref{Surface Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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.
@xseealso{@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{XREFclim,,clim}}
@end deftypefn


@c surfl scripts/plot/draw/surfl.m
@anchor{XREFsurfl}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} surfl (@var{z})
@deftypefnx {} {} surfl (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} surfl (@dots{}, @var{lsrc})
@deftypefnx {} {} surfl (@var{x}, @var{y}, @var{z}, @var{lsrc}, @var{P})
@deftypefnx {} {} surfl (@dots{}, "cdata")
@deftypefnx {} {} surfl (@dots{}, "light")
@deftypefnx {} {} surfl (@var{hax}, @dots{})
@deftypefnx {} {@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.

The alternate mode @qcode{"light"} creates a light object to illuminate the
surface.

The light source location may be specified using @var{lsrc} which can be
a 2-element vector [azimuth, elevation] in degrees, or 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 axes,
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
@xseealso{@ref{XREFdiffuse,,diffuse}, @ref{XREFspecular,,specular}, @ref{XREFsurf,,surf}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFclim,,clim}}
@end deftypefn


@c surfnorm scripts/plot/draw/surfnorm.m
@anchor{XREFsurfnorm}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} surfnorm (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} surfnorm (@var{z})
@deftypefnx {} {} surfnorm (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} surfnorm (@var{hax}, @dots{})
@deftypefnx {} {[@var{Nx}, @var{Ny}, @var{Nz}] =} surfnorm (@dots{})
Find the vectors normal to a meshgridded 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:columns (@var{z})} and @var{y} is
@code{1:rows (@var{z})}.

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

Any property/value input pairs are assigned to the surface object.  The full
list of properties is documented at @ref{Surface Properties}.

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

If output arguments are requested then the components of the normal
vectors are returned in @var{Nx}, @var{Ny}, and @var{Nz} and no plot is
made.  The normal vectors are unnormalized (magnitude != 1).  To normalize,
use

@example
@group
len = sqrt (nx.^2 + ny.^2 + nz.^2);
nx ./= len;  ny ./= len;  nz ./= len;
@end group
@end example

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

@example
surfnorm (peaks (25));
@end example

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

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

@xseealso{@ref{XREFisonormals,,isonormals}, @ref{XREFquiver3,,quiver3}, @ref{XREFsurf,,surf}, @ref{XREFmeshgrid,,meshgrid}}
@end deftypefn


@c isosurface scripts/plot/draw/isosurface.m
@anchor{XREFisosurface}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{fv} =} isosurface (@var{v}, @var{isoval})
@deftypefnx {} {@var{fv} =} isosurface (@var{v})
@deftypefnx {} {@var{fv} =} isosurface (@var{x}, @var{y}, @var{z}, @var{v}, @var{isoval})
@deftypefnx {} {@var{fv} =} isosurface (@var{x}, @var{y}, @var{z}, @var{v})
@deftypefnx {} {@var{fvc} =} isosurface (@dots{}, @var{col})
@deftypefnx {} {@var{fv} =} isosurface (@dots{}, "noshare")
@deftypefnx {} {@var{fv} =} isosurface (@dots{}, "verbose")
@deftypefnx {} {[@var{f}, @var{v}] =} isosurface (@dots{})
@deftypefnx {} {[@var{f}, @var{v}, @var{c}] =} isosurface (@dots{})
@deftypefnx {} {} isosurface (@dots{})

Calculate isosurface of 3-D volume data.

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

The input argument @var{v} is a three-dimensional array that contains data
sampled over a volume.

The input @var{isoval} is a scalar that specifies the value for the
isosurface.  If @var{isoval} is omitted or empty, a @nospell{"good"} value
for an isosurface is determined from @var{v}.

When called with a single output argument @code{isosurface} returns a
structure array @var{fv} that contains the fields @var{faces} and
@var{vertices} computed at the points
@code{[@var{x}, @var{y}, @var{z}] = meshgrid (1:l, 1:m, 1:n)} where
@code{[l, m, n] = size (@var{v})}.  The output @var{fv} can be
used directly as input to the @code{patch} function.

If called with additional input arguments @var{x}, @var{y}, and @var{z}
that are three-dimensional arrays with the same size as @var{v} or
vectors with lengths corresponding to the dimensions of @var{v}, then the
volume data is taken at the specified points.  If @var{x}, @var{y}, or
@var{z} are empty, the grid corresponds to the indices (@code{1:n}) in
the respective direction (@pxref{XREFmeshgrid,,@code{meshgrid}}).

The optional input argument @var{col}, which is a three-dimensional array
of the same size as @var{v}, specifies coloring of the isosurface.  The
color data is interpolated, as necessary, to match @var{isoval}.  The
output structure array, in this case, has the additional field
@var{facevertexcdata}.

If given the string input argument @qcode{"noshare"}, vertices may be
returned multiple times for different faces.  The default behavior is to
eliminate vertices shared by adjacent faces.

The string input argument @qcode{"verbose"} is supported for @sc{matlab}
compatibility, but has no effect.

Any string arguments must be passed after the other arguments.

If called with two or three output arguments, return the information about
the faces @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, the isosurface geometry is directly
plotted with the @code{patch} command and a light object is added to
the axes if not yet present.

For example,

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

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

An example of 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);
v = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2);
figure ();

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

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

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

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

@xseealso{@ref{XREFisonormals,,isonormals}, @ref{XREFisocolors,,isocolors}, @ref{XREFisocaps,,isocaps}, @ref{XREFsmooth3,,smooth3}, @ref{XREFreducevolume,,reducevolume}, @ref{XREFreducepatch,,reducepatch}, @ref{XREFpatch,,patch}}
@end deftypefn


@c isonormals scripts/plot/draw/isonormals.m
@anchor{XREFisonormals}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{vn} =} isonormals (@var{val}, @var{vert})
@deftypefnx {} {@var{vn} =} isonormals (@var{val}, @var{hp})
@deftypefnx {} {@var{vn} =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{vert})
@deftypefnx {} {@var{vn} =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{hp})
@deftypefnx {} {@var{vn} =} isonormals (@dots{}, "negate")
@deftypefnx {} {} isonormals (@var{val}, @var{hp})
@deftypefnx {} {} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{hp})
@deftypefnx {} {} isonormals (@dots{}, "negate")

Calculate normals to an isosurface.

The vertex normals @var{vn} are calculated from the gradient of the
3-dimensional array @var{val} (size: lxmxn) containing the data for an
isosurface geometry.  The normals point towards smaller values in @var{val}.

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

If called with additional input arguments @var{x}, @var{y}, and @var{z},
which are 3-dimensional arrays with the same size as @var{val},
then the volume data is taken at these points.  Instead of the vertex data
@var{vert}, a patch handle @var{hp} can be passed to the function.

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

If no output argument is given, the property @qcode{"VertexNormals"} of
the patch associated with the patch handle @var{hp} is changed directly.

@xseealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisocolors,,isocolors}, @ref{XREFsmooth3,,smooth3}}
@end deftypefn


@c isocaps scripts/plot/draw/isocaps.m
@anchor{XREFisocaps}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{fvc} =} isocaps (@var{v}, @var{isoval})
@deftypefnx {} {@var{fvc} =} isocaps (@var{v})
@deftypefnx {} {@var{fvc} =} isocaps (@var{x}, @var{y}, @var{z}, @var{v}, @var{isoval})
@deftypefnx {} {@var{fvc} =} isocaps (@var{x}, @var{y}, @var{z}, @var{v})
@deftypefnx {} {@var{fvc} =} isocaps (@dots{}, @var{which_caps})
@deftypefnx {} {@var{fvc} =} isocaps (@dots{}, @var{which_plane})
@deftypefnx {} {@var{fvc} =} isocaps (@dots{}, @qcode{"verbose"})
@deftypefnx {} {[@var{faces}, @var{vertices}, @var{fvcdata}] =} isocaps (@dots{})
@deftypefnx {} {} isocaps (@dots{})

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

This function places caps at the open ends of isosurfaces.

The input argument @var{v} is a three-dimensional array that contains data
sampled over a volume.

The input @var{isoval} is a scalar that specifies the value for the
isosurface.  If @var{isoval} is omitted or empty, a @nospell{"good"} value
for an isosurface is determined from @var{v}.

When called with a single output argument, @code{isocaps} returns a
structure array @var{fvc} with the fields: @code{faces}, @code{vertices},
and @code{facevertexcdata}.  The results are computed at the points
@code{[@var{x}, @var{y}, @var{z}] = meshgrid (1:l, 1:m, 1:n)} where
@code{[l, m, n] = size (@var{v})}.  The output @var{fvc} can be used
directly as input to the @code{patch} function.

If called with additional input arguments @var{x}, @var{y}, and @var{z}
that are three-dimensional arrays with the same size as @var{v} or
vectors with lengths corresponding to the dimensions of @var{v}, then the
volume data is taken at the specified points.  If @var{x}, @var{y}, or
@var{z} are empty, the grid corresponds to the indices (@code{1:n}) in
the respective direction (@pxref{XREFmeshgrid,,@code{meshgrid}}).

The optional parameter @var{which_caps} can have one of the following
string values which defines how the data will be enclosed:

@table @asis
@item @qcode{"above"}, @qcode{"a"} (default)
for end-caps that enclose the data above @var{isoval}.

@item @qcode{"below"}, @qcode{"b"}
for end-caps that enclose the data below @var{isoval}.
@end table

The optional parameter @var{which_plane} can have one of the following
string values to define which end-cap should be drawn:

@table @asis
@item @qcode{"all"} (default)
for all of the end-caps.

@item @qcode{"xmin"}
for end-caps at the lower x-plane of the data.

@item @qcode{"xmax"}
for end-caps at the upper x-plane of the data.

@item @qcode{"ymin"}
for end-caps at the lower y-plane of the data.

@item @qcode{"ymax"}
for end-caps at the upper y-plane of the data.

@item @qcode{"zmin"}
for end-caps at the lower z-plane of the data.

@item @qcode{"zmax"}
for end-caps at the upper z-plane of the data.
@end table

The string input argument @qcode{"verbose"} is supported for @sc{matlab}
compatibility, but has no effect.

If called with two or three output arguments, the data for faces
@var{faces}, vertices @var{vertices}, and the color data
@var{facevertexcdata} are returned in separate arrays instead of a single
structure.

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

@xseealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisonormals,,isonormals}, @ref{XREFpatch,,patch}}
@end deftypefn


@c isocolors scripts/plot/draw/isocolors.m
@anchor{XREFisocolors}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{cdat} =} isocolors (@var{c}, @var{v})
@deftypefnx {} {@var{cdat} =} isocolors (@var{x}, @var{y}, @var{z}, @var{c}, @var{v})
@deftypefnx {} {@var{cdat} =} isocolors (@var{x}, @var{y}, @var{z}, @var{r}, @var{g}, @var{b}, @var{v})
@deftypefnx {} {@var{cdat} =} isocolors (@var{r}, @var{g}, @var{b}, @var{v})
@deftypefnx {} {@var{cdat} =} isocolors (@dots{}, @var{hp})
@deftypefnx {} {} isocolors (@dots{}, @var{hp})

Compute isosurface colors.

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

If called with additional input arguments @var{x}, @var{y} and @var{z} which
are three-dimensional arrays of the same size as @var{c} then the
color data is taken at those specified points.

Instead of indexed color data @var{c}, @code{isocolors} can also be called
with RGB values @var{r}, @var{g}, @var{b}.  If input arguments @var{x},
@var{y}, @var{z} are not given then @code{meshgrid} computed values are
used.

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

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


@c smooth3 scripts/plot/draw/smooth3.m
@anchor{XREFsmooth3}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{smoothed_data} =} smooth3 (@var{data})
@deftypefnx {} {@var{smoothed_data} =} smooth3 (@var{data}, @var{method})
@deftypefnx {} {@var{smoothed_data} =} smooth3 (@var{data}, @var{method}, @var{sz})
@deftypefnx {} {@var{smoothed_data} =} smooth3 (@var{data}, @var{method}, @var{sz}, @var{std_dev})
Smooth values of 3-dimensional matrix @var{data}.

This function may be used, for example, to reduce the impact of noise in
@var{data} before calculating isosurfaces.

@var{data} must be a non-singleton 3-dimensional matrix.  The output
@var{smoothed_data} is a matrix of the same size as @var{data}.

The option input @var{method} determines which convolution kernel is used
for the smoothing process.  Possible choices:

@table @asis
@item @qcode{"box"}, @qcode{"b"} (default)
a convolution kernel with sharp edges.

@item @qcode{"gaussian"}, @qcode{"g"}
a convolution kernel that is represented by a non-correlated trivariate
normal distribution function.
@end table

@var{sz} is either a 3-element vector specifying the size of the
convolution kernel in the x-, y- and z-directions, or a scalar.  In the
scalar case the same size is used for all three dimensions
(@code{[@var{sz}, @var{sz}, @var{sz}]}).  The default value is 3.

If @var{method} is @qcode{"gaussian"} then the optional input @var{std_dev}
defines the standard deviation of the trivariate normal distribution
function.  @var{std_dev} is either a 3-element vector specifying the
standard deviation of the Gaussian convolution kernel in x-, y- and
z-directions, or a scalar.  In the scalar case the same value is used for
all three dimensions.  The default value is 0.65.

@xseealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisonormals,,isonormals}, @ref{XREFpatch,,patch}}
@end deftypefn


@c reducevolume scripts/plot/draw/reducevolume.m
@anchor{XREFreducevolume}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{nx}, @var{ny}, @var{nz}, @var{nv}] =} reducevolume (@var{v}, @var{r})
@deftypefnx {} {[@var{nx}, @var{ny}, @var{nz}, @var{nv}] =} reducevolume (@var{x}, @var{y}, @var{z}, @var{v}, @var{r})
@deftypefnx {} {@var{nv} =} reducevolume (@dots{})

Reduce the volume of the dataset in @var{v} according to the values in
@var{r}.

@var{v} is a matrix that is non-singleton in the first 3 dimensions.

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

@code{reducevolume} reduces the number of elements of @var{v} by taking
only every @var{r}-th element in the respective dimension.

Optionally, @var{x}, @var{y}, and @var{z} can be supplied to represent the
set of coordinates of @var{v}.  They can either be matrices of the same size
as @var{v} or vectors with sizes according to the dimensions of @var{v}, in
which case they are expanded to matrices
(@pxref{XREFmeshgrid,,@code{meshgrid}}).

If @code{reducevolume} is called with two arguments then @var{x}, @var{y},
and @var{z} are assumed to match the respective indices of @var{v}.

The reduced matrix is returned in @var{nv}.

Optionally, the reduced set of coordinates are returned in @var{nx},
@var{ny}, and @var{nz}, respectively.

Examples:

@example
@group
@var{v} = reshape (1:6*8*4, [6 8 4]);
@var{nv} = reducevolume (@var{v}, [4 3 2]);
@end group
@end example

@example
@group
@var{v} = reshape (1:6*8*4, [6 8 4]);
@var{x} = 1:3:24;  @var{y} = -14:5:11;  @var{z} = linspace (16, 18, 4);
[@var{nx}, @var{ny}, @var{nz}, @var{nv}] = reducevolume (@var{x}, @var{y}, @var{z}, @var{v}, [4 3 2]);
@end group
@end example

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


@c reducepatch scripts/plot/draw/reducepatch.m
@anchor{XREFreducepatch}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{reduced_fv} =} reducepatch (@var{fv})
@deftypefnx {} {@var{reduced_fv} =} reducepatch (@var{faces}, @var{vertices})
@deftypefnx {} {@var{reduced_fv} =} reducepatch (@var{patch_handle})
@deftypefnx {} {} reducepatch (@var{patch_handle})
@deftypefnx {} {@var{reduced_fv} =} reducepatch (@dots{}, @var{reduction_factor})
@deftypefnx {} {@var{reduced_fv} =} reducepatch (@dots{}, "fast")
@deftypefnx {} {@var{reduced_fv} =} reducepatch (@dots{}, "verbose")
@deftypefnx {} {[@var{reduced_faces}, @var{reduces_vertices}] =} reducepatch (@dots{})

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

The input patch can be represented by a structure @var{fv} with the
fields @code{faces} and @code{vertices}, by two matrices @var{faces} and
@var{vertices} (see, e.g., the result of @code{isosurface}), or by a
handle to a patch object @var{patch_handle}
(@pxref{XREFpatch,,@code{patch}}).

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

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

If @code{reducepatch} is called with a handle to a valid patch
@var{patch_handle}, and without any output arguments, then the given
patch is updated immediately.

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

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

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

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

If called with one output argument, the reduced faces and vertices are
returned in a structure @var{reduced_fv} with the fields @code{faces} and
@code{vertices} (see the one output option of @code{isosurface}).

If called with two output arguments, the reduced faces and vertices are
returned in two separate matrices @var{reduced_faces} and
@var{reduced_vertices}.

@xseealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisonormals,,isonormals}, @ref{XREFreducevolume,,reducevolume}, @ref{XREFpatch,,patch}}
@end deftypefn


@c shrinkfaces scripts/plot/draw/shrinkfaces.m
@anchor{XREFshrinkfaces}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} shrinkfaces (@var{p}, @var{sf})
@deftypefnx {} {@var{nfv} =} shrinkfaces (@var{p}, @var{sf})
@deftypefnx {} {@var{nfv} =} shrinkfaces (@var{fv}, @var{sf})
@deftypefnx {} {@var{nfv} =} shrinkfaces (@var{f}, @var{v}, @var{sf})
@deftypefnx {} {[@var{nf}, @var{nv}] =} shrinkfaces (@dots{})

Reduce the size of faces in a patch by the shrink factor @var{sf}.

The patch object can be specified by a graphics handle (@var{p}), a patch
structure (@var{fv}) with the fields @qcode{"faces"} and @qcode{"vertices"},
or as two separate matrices (@var{f}, @var{v}) of faces and vertices.

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

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

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

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

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

@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

@xseealso{@ref{XREFpatch,,patch}}
@end deftypefn


@c diffuse scripts/plot/appearance/diffuse.m
@anchor{XREFdiffuse}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{d} =} diffuse (@var{sx}, @var{sy}, @var{sz}, @var{lv})
Calculate the 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 a 2-element vector
[azimuth, elevation] in degrees or as a 3-element vector [x, y, z].
@xseealso{@ref{XREFspecular,,specular}, @ref{XREFsurfl,,surfl}}
@end deftypefn


@c specular scripts/plot/appearance/specular.m
@anchor{XREFspecular}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{refl} =} specular (@var{sx}, @var{sy}, @var{sz}, @var{lv}, @var{vv})
@deftypefnx {} {@var{refl} =} specular (@var{sx}, @var{sy}, @var{sz}, @var{lv}, @var{vv}, @var{se})
Calculate the 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 are specified using
parameters @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 specifies the specular exponent (spread)
@var{se}.  If not given, @var{se} defaults to 10.
@xseealso{@ref{XREFdiffuse,,diffuse}, @ref{XREFsurfl,,surfl}}
@end deftypefn


@c lighting scripts/plot/appearance/lighting.m
@anchor{XREFlighting}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} lighting (@var{type})
@deftypefnx {} {} lighting (@var{hax}, @var{type})
Set the lighting of patch or surface graphic objects.

Valid arguments for @var{type} are

@table @asis
@item @qcode{"flat"}
Draw objects with faceted lighting effects.

@item @qcode{"gouraud"}
Draw objects with linear interpolation of the lighting effects between the
vertices.

@item @qcode{"none"}
Draw objects without light and shadow effects.
@end table

If the first argument @var{hax} is an axes handle, then change the lighting
effects of objects in this axes, rather than the current axes returned by
@code{gca}.

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

@xseealso{@ref{XREFlight,,light}, @ref{XREFfill,,fill}, @ref{XREFmesh,,mesh}, @ref{XREFpatch,,patch}, @ref{XREFpcolor,,pcolor}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}, @ref{XREFshading,,shading}}
@end deftypefn


@c material scripts/plot/appearance/material.m
@anchor{XREFmaterial}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} material shiny
@deftypefnx {} {} material dull
@deftypefnx {} {} material metal
@deftypefnx {} {} material default
@deftypefnx {} {} material ([@var{as}, @var{ds}, @var{ss}])
@deftypefnx {} {} material ([@var{as}, @var{ds}, @var{ss}, @var{se}])
@deftypefnx {} {} material ([@var{as}, @var{ds}, @var{ss}, @var{se}, @var{scr}])
@deftypefnx {} {} material (@var{hlist}, @dots{})
@deftypefnx {} {@var{mtypes} =} material ()
@deftypefnx {} {@var{refl_props} =} material (@var{mtype_string})
Set reflectance properties for the lighting of surfaces and patches.

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

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

@multitable @columnfractions .16 .16 .16 .16 .16 .16
@headitem @var{mtype} @tab ambient- strength @tab diffuse-
strength @tab specular- strength @tab specular- exponent @tab specular-
color- reflectance
@item @qcode{"shiny"} @tab 0.3 @tab 0.6 @tab 0.9 @tab 20 @tab 1.0
@item @qcode{"dull"} @tab 0.3 @tab 0.8 @tab 0.0 @tab 10 @tab 1.0
@item @qcode{"metal"} @tab 0.3 @tab 0.3 @tab 1.0 @tab 25 @tab 0.5
@item @qcode{"default"} @tab @qcode{"default"} @tab @qcode{"default"} @tab @qcode{"default"}
@tab @qcode{"default"} @tab @qcode{"default"}
@end multitable

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

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

Additionally, @code{material} can be called with a single output argument.
If called without input arguments, a column cell vector @var{mtypes} with
the strings for all available materials is returned.  If the one input
argument @var{mtype_string} is the name of a material, a 1x5 cell vector
@var{refl_props} with the reflectance properties of that material is
returned.  In both cases, no graphic properties are changed.

@xseealso{@ref{XREFlight,,light}, @ref{XREFfill,,fill}, @ref{XREFmesh,,mesh}, @ref{XREFpatch,,patch}, @ref{XREFpcolor,,pcolor}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}}
@end deftypefn


@c camlight scripts/plot/draw/camlight.m
@anchor{XREFcamlight}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} camlight {}
@deftypefnx {} {} camlight right
@deftypefnx {} {} camlight left
@deftypefnx {} {} camlight headlight
@deftypefnx {} {} camlight (@var{az}, @var{el})
@deftypefnx {} {} camlight (@dots{}, @var{style})
@deftypefnx {} {} camlight (@var{hl}, @dots{})
@deftypefnx {} {} camlight (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} camlight (@dots{})
Add a light object to a figure using a simple interface.

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

For more control, the light position can be specified by an azimuthal
rotation @var{az} and an elevation angle @var{el}, both in degrees,
relative to the current properties of the camera.

The optional string @var{style} specifies whether the light is a local point
source (@qcode{"local"}, the default) or placed at infinite distance
(@qcode{"infinite"}).

If the first argument @var{hl} is a handle to a light object, then act on
this light object rather than creating a new object.

If the first argument @var{hax} is an axes handle, then create a new light
object in this axes, rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the light object.
This can be used to move or further change properties of the light object.

Examples:

Add a light object to a plot

@example
@group
@c doctest: +SKIP
sphere (36);
camlight
@end group
@end example

Position the light source exactly

@example
@group
@c doctest: +SKIP
camlight (45, 30);
@end group
@end example

Here the light is first pitched upwards (@pxref{XREFcamup,,@code{camup}})
from the camera position (@pxref{XREFcampos,,@code{campos}}) by 30
degrees.  It is then yawed by 45 degrees to the right.  Both rotations
are centered around the camera target
(@pxref{XREFcamtarget,,@code{camtarget}}).

Return a handle to further manipulate the light object

@example
@group
@c doctest: +SKIP
clf
sphere (36);
hl = camlight ("left");
set (hl, "color", "r");
@end group
@end example

@xseealso{@ref{XREFlight,,light}}
@end deftypefn


@c lightangle scripts/plot/draw/lightangle.m
@anchor{XREFlightangle}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} lightangle (@var{az}, @var{el})
@deftypefnx {} {} lightangle (@var{hax}, @var{az}, @var{el})
@deftypefnx {} {} lightangle (@var{hl}, @var{az}, @var{el})
@deftypefnx {} {@var{hl} =} lightangle (@dots{})
@deftypefnx {} {[@var{az}, @var{el}] =} lightangle (@var{hl})
Add a light object to the current axes using spherical coordinates.

The light position is specified by an azimuthal rotation @var{az} and an
elevation angle @var{el}, both in degrees.

If the first argument @var{hax} is an axes handle, then create a new light
object in this axes, rather than the current axes returned by @code{gca}.

If the first argument @var{hl} is a handle to a light object, then act on
this light object rather than creating a new object.

The optional return value @var{hl} is a graphics handle to the light object.

Example:

Add a light object to a plot

@example
@group
@c doctest: +SKIP
clf;
sphere (36);
lightangle (45, 30);
@end group
@end example

@xseealso{@ref{XREFlight,,light}, @ref{XREFview,,view}, @ref{XREFcamlight,,camlight}}
@end deftypefn


@c meshgrid scripts/plot/util/meshgrid.m
@anchor{XREFmeshgrid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{xx}, @var{yy}] =} meshgrid (@var{x}, @var{y})
@deftypefnx {} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x}, @var{y}, @var{z})
@deftypefnx {} {[@var{xx}, @var{yy}] =} meshgrid (@var{x})
@deftypefnx {} {[@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.  If @var{z} is omitted and @var{zz} is
requested, it is assumed to be the same as @var{y}.

@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.
@xseealso{@ref{XREFndgrid,,ndgrid}, @ref{XREFmesh,,mesh}, @ref{XREFcontour,,contour}, @ref{XREFsurf,,surf}}
@end deftypefn


@c ndgrid scripts/plot/util/ndgrid.m
@anchor{XREFndgrid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{y1}, @var{y2}, @dots{}, @var{y}n] =} ndgrid (@var{x1}, @var{x2}, @dots{}, @var{x}n)
@deftypefnx {} {[@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.
@xseealso{@ref{XREFmeshgrid,,meshgrid}}
@end deftypefn


@c plot3 scripts/plot/draw/plot3.m
@anchor{XREFplot3}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} plot3 (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} plot3 (@var{x}, @var{y}, @var{z}, @var{prop}, @var{value}, @dots{})
@deftypefnx {} {} plot3 (@var{x}, @var{y}, @var{z}, @var{fmt})
@deftypefnx {} {} plot3 (@var{x}, @var{cplx})
@deftypefnx {} {} plot3 (@var{cplx})
@deftypefnx {} {} plot3 (@var{hax}, @dots{})
@deftypefnx {} {@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}.
The full list of properties is documented at
@ref{Line Properties}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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
@xseealso{@ref{XREFezplot3,,ezplot3}, @ref{XREFplot,,plot}}
@end deftypefn


@c view scripts/plot/appearance/view.m
@anchor{XREFview}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} view (@var{azimuth}, @var{elevation})
@deftypefnx {} {} view ([@var{azimuth} @var{elevation}])
@deftypefnx {} {} view ([@var{x} @var{y} @var{z}])
@deftypefnx {} {} view (2)
@deftypefnx {} {} view (3)
@deftypefnx {} {} view (@var{hax}, @dots{})
@deftypefnx {} {[@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 axes 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 camlookat scripts/plot/appearance/camlookat.m
@anchor{XREFcamlookat}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} camlookat ()
@deftypefnx {} {} camlookat (@var{h})
@deftypefnx {} {} camlookat (@var{handle_list})
@deftypefnx {} {} camlookat (@var{hax})
Move the camera and adjust its properties to look at objects.

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

This command fixes the camera's viewing direction
(@code{camtarget() - campos()}), camera up vector
(@pxref{XREFcamup,,@code{camup}}) and viewing angle
(@pxref{XREFcamva,,@code{camva}}).  The camera target
(@pxref{XREFcamtarget,,@code{camtarget}}) and camera position
(@pxref{XREFcampos,,@code{campos}}) are changed.

If the argument is a list @var{handle_list}, then a single bounding box for
all the objects is computed and the camera is then adjusted as above.

If the argument is an axis object @var{hax}, then the children of the axis
are used as @var{handle_list}.  When called with no inputs, it uses the
current axis (@pxref{XREFgca,,@code{gca}}).

@xseealso{@ref{XREFcamorbit,,camorbit}, @ref{XREFcamzoom,,camzoom}, @ref{XREFcamroll,,camroll}}
@end deftypefn


@c campos scripts/plot/appearance/campos.m
@anchor{XREFcampos}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{p} =} campos ()
@deftypefnx {} {} campos ([@var{x} @var{y} @var{z}])
@deftypefnx {} {@var{mode} =} campos ("mode")
@deftypefnx {} {} campos (@var{mode})
@deftypefnx {} {} campos (@var{hax}, @dots{})
Get or set the camera position.

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

@example
@group
hf = figure();
peaks()
p = campos ()
  @result{} p =
      -27.394  -35.701   64.079
@end group
@end example

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

@example
@group
campos (p + [0 0 10])
campos ()
  @result{} ans =
      -27.394  -35.701   74.079
@end group
@end example

Having made that change, the camera position @var{mode} is now manual:

@example
@group
campos ("mode")
  @result{} manual
@end group
@end example

We can set it back to automatic:

@example
@group
campos ("auto")
campos ()
  @result{} ans =
      -27.394  -35.701   64.079
close (hf)
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{hax}.

@xseealso{@ref{XREFcamup,,camup}, @ref{XREFcamtarget,,camtarget}, @ref{XREFcamva,,camva}}
@end deftypefn


@c camorbit scripts/plot/appearance/camorbit.m
@anchor{XREFcamorbit}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} camorbit (@var{theta}, @var{phi})
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, @var{coorsys})
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, @var{coorsys}, @var{dir})
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data")
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", "z")
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", "x")
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", "y")
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", [@var{x} @var{y} @var{z}])
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "camera")
@deftypefnx {} {} camorbit (@var{hax}, @dots{})
Rotate the camera up/down and left/right around its target.

Move the camera @var{phi} degrees up and @var{theta} degrees to the right,
as if it were in an orbit around its target.
Example:

@example
@group
@c doctest: +SKIP
sphere ()
camorbit (30, 20)
@end group
@end example

These rotations are centered around the camera target
(@pxref{XREFcamtarget,,@code{camtarget}}).
First the camera position is pitched up or down by rotating it @var{phi}
degrees around an axis orthogonal to both the viewing direction
(specifically @code{camtarget() - campos()}) and the camera ``up vector''
(@pxref{XREFcamup,,@code{camup}}).
Example:

@example
@group
@c doctest: +SKIP
camorbit (0, 20)
@end group
@end example

The second rotation depends on the coordinate system @var{coorsys} and
direction @var{dir} inputs.
The default for @var{coorsys} is @qcode{"data"}.  In this case, the camera
is yawed left or right by rotating it @var{theta} degrees around an axis
specified by @var{dir}.
The default for @var{dir} is @qcode{"z"}, corresponding to the vector
@code{[0, 0, 1]}.
Example:

@example
@group
@c doctest: +SKIP
camorbit (30, 0)
@end group
@end example

When @var{coorsys} is set to @qcode{"camera"}, the camera is moved left or
right by rotating it around an axis parallel to the camera up vector
(@pxref{XREFcamup,,@code{camup}}).
The input @var{dir} should not be specified in this case.
Example:

@example
@group
@c doctest: +SKIP
camorbit (30, 0, "camera")
@end group
@end example

(Note: the rotation by @var{phi} is unaffected by @qcode{"camera"}.)

The @code{camorbit} command modifies two camera properties:
@ref{XREFcampos,,@code{campos}} and @ref{XREFcamup,,@code{camup}}.

By default, this command affects the current axis; alternatively, an axis
can be specified by the optional argument @var{hax}.

@xseealso{@ref{XREFcamzoom,,camzoom}, @ref{XREFcamroll,,camroll}, @ref{XREFcamlookat,,camlookat}}
@end deftypefn


@c camroll scripts/plot/appearance/camroll.m
@anchor{XREFcamroll}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} camroll (@var{theta})
@deftypefnx {} {} camroll (@var{hax}, @var{theta})
Roll the camera.

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

@example
@group
@c doctest: +SKIP
peaks ()
camroll (30)
@end group
@end example

Roll the camera back:

@example
@group
@c doctest: +SKIP
camroll (-30)
@end group
@end example

The following command restores the default camera roll:

@example
@group
@c doctest: +SKIP
camup ("auto")
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{hax}.

@xseealso{@ref{XREFcamzoom,,camzoom}, @ref{XREFcamorbit,,camorbit}, @ref{XREFcamlookat,,camlookat}, @ref{XREFcamup,,camup}}
@end deftypefn


@c camtarget scripts/plot/appearance/camtarget.m
@anchor{XREFcamtarget}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{t} =} camtarget ()
@deftypefnx {} {} camtarget ([@var{x} @var{y} @var{z}])
@deftypefnx {} {@var{mode} =} camtarget ("mode")
@deftypefnx {} {} camtarget (@var{mode})
@deftypefnx {} {} camtarget (@var{hax}, @dots{})
Get or set where the camera is pointed.

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

@example
@group
hf = figure();
sphere (36)
v = camtarget ()
  @result{} v =
      0   0   0
@end group
@end example

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

@example
@group
camtarget ([1 1 1])
camtarget ()
  @result{}   1   1   1
@end group
@end example

Having done so, the camera target @var{mode} is manual:

@example
@group
camtarget ("mode")
  @result{} manual
@end group
@end example

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

@example
@group
hold on;
peaks ()
camtarget ()
  @result{}   1   1   1
@end group
@end example

We can reset it to be automatic:

@example
@group
@c doctest: +XFAIL
@c https://savannah.gnu.org/bugs/?44503
camtarget ("auto")
camtarget ()
  @result{}   0   0   0.76426
close (hf)
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{hax}.

@xseealso{@ref{XREFcampos,,campos}, @ref{XREFcamup,,camup}, @ref{XREFcamva,,camva}}
@end deftypefn


@c camup scripts/plot/appearance/camup.m
@anchor{XREFcamup}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{up} =} camup ()
@deftypefnx {} {} camup ([@var{x} @var{y} @var{z}])
@deftypefnx {} {@var{mode} =} camup ("mode")
@deftypefnx {} {} camup (@var{mode})
@deftypefnx {} {} camup (@var{hax}, @dots{})
Get or set the camera up vector.

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

@example
@group
hf = figure ();
sphere (36)
v = camup ()
  @result{} v =
      0   0   1
@end group
@end example

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

@example
@group
camup ([1 1 0])
camup ()
  @result{}   1   1   0
camup ("mode")
  @result{} manual
@end group
@end example

Modifying the up vector does not modify the camera target
(@pxref{XREFcamtarget,,@code{camtarget}}).  Thus, the camera up vector might
not be orthogonal to the direction of the camera's view:

@example
@group
camup ([1 2 3])
dot (camup (), camtarget () - campos ())
  @result{} 6...
@end group
@end example

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

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

@example
@group
camup ("auto")
camup ()
  @result{}   0   0   1
close (hf)
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{hax}.

@xseealso{@ref{XREFcampos,,campos}, @ref{XREFcamtarget,,camtarget}, @ref{XREFcamva,,camva}}
@end deftypefn


@c camva scripts/plot/appearance/camva.m
@anchor{XREFcamva}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{a} =} camva ()
@deftypefnx {} {} camva (@var{a})
@deftypefnx {} {@var{mode} =} camva ("mode")
@deftypefnx {} {} camva (@var{mode})
@deftypefnx {} {} camva (@var{hax}, @dots{})
Get or set the camera viewing angle.

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

@example
@group
hf = figure();
sphere (36)
a = camva ()
  @result{} a =  10.340
@end group
@end example

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

@example
@group
camva (2*a)
camva ("mode")
  @result{} manual
@end group
@end example

We can set it back to automatic:

@example
@group
camva ("auto")
camva ("mode")
  @result{} auto
camva ()
  @result{} ans =  10.340
close (hf)
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{hax}.

@xseealso{@ref{XREFcampos,,campos}, @ref{XREFcamtarget,,camtarget}, @ref{XREFcamup,,camup}}
@end deftypefn


@c camzoom scripts/plot/appearance/camzoom.m
@anchor{XREFcamzoom}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} camzoom (@var{zf})
@deftypefnx {} {} camzoom (@var{hax}, @var{zf})
Zoom the camera in or out.

A value of @var{zf} larger than 1 ``zooms in'' such that the scene appears
magnified:

@example
@group
hf = figure ();
sphere (36)
camzoom (1.2)
@end group
@end example

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

@example
@group
camzoom (0.5)
@end group
@end example

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

@example
@group
camva ("auto")
close (hf)
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{hax}.

@xseealso{@ref{XREFcamroll,,camroll}, @ref{XREFcamorbit,,camorbit}, @ref{XREFcamlookat,,camlookat}, @ref{XREFcamva,,camva}}
@end deftypefn


@c slice scripts/plot/draw/slice.m
@anchor{XREFslice}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} slice (@var{x}, @var{y}, @var{z}, @var{v}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} slice (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {} {} slice (@var{v}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} slice (@var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {} {} slice (@dots{}, @var{method})
@deftypefnx {} {} slice (@var{hax}, @dots{})
@deftypefnx {} {@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{y}, 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 axes,
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
@xseealso{@ref{XREFinterp3,,interp3}, @ref{XREFsurface,,surface}, @ref{XREFpcolor,,pcolor}}
@end deftypefn


@c ribbon scripts/plot/draw/ribbon.m
@anchor{XREFribbon}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ribbon (@var{y})
@deftypefnx {} {} ribbon (@var{x}, @var{y})
@deftypefnx {} {} ribbon (@var{x}, @var{y}, @var{width})
@deftypefnx {} {} ribbon (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ribbon (@dots{})
Draw a ribbon plot for the columns of @var{y} vs. @var{x}.

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

The optional parameter @var{width} specifies the width of a single ribbon
(default is 0.75).

If the first argument @var{hax} is an axes handle, then plot into this axes,
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.
@xseealso{@ref{XREFsurface,,surface}, @ref{XREFwaterfall,,waterfall}}
@end deftypefn


@c shading scripts/plot/appearance/shading.m
@anchor{XREFshading}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} shading (@var{type})
@deftypefnx {} {} 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 black edges.

@item @qcode{"interp"}
Colors 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 axes,
rather than the current axes returned by @code{gca}.
@xseealso{@ref{XREFfill,,fill}, @ref{XREFmesh,,mesh}, @ref{XREFpatch,,patch}, @ref{XREFpcolor,,pcolor}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}, @ref{XREFhidden,,hidden}, @ref{XREFlighting,,lighting}}
@end deftypefn


@c scatter3 scripts/plot/draw/scatter3.m
@anchor{XREFscatter3}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} scatter3 (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s})
@deftypefnx {} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}, @var{c})
@deftypefnx {} {} scatter3 (@dots{}, @var{style})
@deftypefnx {} {} scatter3 (@dots{}, "filled")
@deftypefnx {} {} scatter3 (@dots{}, @var{prop}, @var{val})
@deftypefnx {} {} scatter3 (@var{hax}, @dots{})
@deftypefnx {} {@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.

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

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

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

Programming Note: The full list of properties is documented at
@ref{Scatter Properties}.
@xseealso{@ref{XREFscatter,,scatter}, @ref{XREFpatch,,patch}, @ref{XREFplot,,plot}}
@end deftypefn


@c waterfall scripts/plot/draw/waterfall.m
@anchor{XREFwaterfall}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} waterfall (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} waterfall (@var{z})
@deftypefnx {} {} waterfall (@dots{}, @var{c})
@deftypefnx {} {} waterfall (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} waterfall (@var{hax}, @dots{})
@deftypefnx {} {@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{clim} 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.  The full list of properties is documented at
@ref{Surface Properties}.

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

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

@xseealso{@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{XREFclim,,clim}}
@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{data_aspect_ratio} =} daspect ()
@deftypefnx {} {} daspect (@var{data_aspect_ratio})
@deftypefnx {} {} daspect (@var{mode})
@deftypefnx {} {@var{data_aspect_ratio_mode} =} daspect ("mode")
@deftypefnx {} {} 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.

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{plot_box_aspect_ratio} =} pbaspect ( )
@deftypefnx {} {} pbaspect (@var{plot_box_aspect_ratio})
@deftypefnx {} {} pbaspect (@var{mode})
@deftypefnx {} {@var{plot_box_aspect_ratio_mode} =} pbaspect ("mode")
@deftypefnx {} {} 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.

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ezplot3 (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {} ezplot3 (@dots{}, @var{dom})
@deftypefnx {} {} ezplot3 (@dots{}, @var{n})
@deftypefnx {} {} ezplot3 (@dots{}, "animate")
@deftypefnx {} {} ezplot3 (@var{hax}, @dots{})
@deftypefnx {} {@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 @qcode{"animate"} option is given then the plotting is animated
in the style of @code{comet3}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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

@xseealso{@ref{XREFplot3,,plot3}, @ref{XREFcomet3,,comet3}, @ref{XREFezplot,,ezplot}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezsurf,,ezsurf}}
@end deftypefn


@c ezmesh scripts/plot/draw/ezmesh.m
@anchor{XREFezmesh}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ezmesh (@var{f})
@deftypefnx {} {} ezmesh (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {} ezmesh (@dots{}, @var{dom})
@deftypefnx {} {} ezmesh (@dots{}, @var{n})
@deftypefnx {} {} ezmesh (@dots{}, "circ")
@deftypefnx {} {} ezmesh (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ezmeshc (@var{f})
@deftypefnx {} {} ezmeshc (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {} ezmeshc (@dots{}, @var{dom})
@deftypefnx {} {} ezmeshc (@dots{}, @var{n})
@deftypefnx {} {} ezmeshc (@dots{}, "circ")
@deftypefnx {} {} ezmeshc (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ezsurf (@var{f})
@deftypefnx {} {} ezsurf (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {} ezsurf (@dots{}, @var{dom})
@deftypefnx {} {} ezsurf (@dots{}, @var{n})
@deftypefnx {} {} ezsurf (@dots{}, "circ")
@deftypefnx {} {} ezsurf (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ezsurfc (@var{f})
@deftypefnx {} {} ezsurfc (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {} ezsurfc (@dots{}, @var{dom})
@deftypefnx {} {} ezsurfc (@dots{}, @var{n})
@deftypefnx {} {} ezsurfc (@dots{}, "circ")
@deftypefnx {} {} ezsurfc (@var{hax}, @dots{})
@deftypefnx {} {@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 axes,
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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} cylinder
@deftypefnx {} {} cylinder (@var{r})
@deftypefnx {} {} cylinder (@var{r}, @var{n})
@deftypefnx {} {} cylinder (@var{hax}, @dots{})
@deftypefnx {} {[@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
circumference of the cylinder.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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
@xseealso{@ref{XREFellipsoid,,ellipsoid}, @ref{XREFrectangle,,rectangle}, @ref{XREFsphere,,sphere}}
@end deftypefn


@c sphere scripts/plot/draw/sphere.m
@anchor{XREFsphere}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} sphere ()
@deftypefnx {} {} sphere (@var{n})
@deftypefnx {} {} sphere (@var{hax}, @dots{})
@deftypefnx {} {[@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
circumference of the sphere.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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
@xseealso{@ref{XREFcylinder,,cylinder}, @ref{XREFellipsoid,,ellipsoid}, @ref{XREFrectangle,,rectangle}}
@end deftypefn


@c ellipsoid scripts/plot/draw/ellipsoid.m
@anchor{XREFellipsoid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ellipsoid (@var{xc}, @var{yc}, @var{zc}, @var{xr}, @var{yr}, @var{zr})
@deftypefnx {} {} ellipsoid (@dots{}, @var{n})
@deftypefnx {} {} ellipsoid (@var{hax}, @dots{})
@deftypefnx {} {[@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
circumference of the cylinder.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axes,
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.
@xseealso{@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.

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

@c title scripts/plot/appearance/title.m
@anchor{XREFtitle}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} title (@var{string})
@deftypefnx {} {} title (@var{string}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} title (@var{hax}, @dots{})
@deftypefnx {} {@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 or legend handle, then add a
title to this object, rather than the current axes returned by @code{gca}.

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


@c legend scripts/plot/appearance/legend.m
@anchor{XREFlegend}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} legend ()
@deftypefnx {} {} legend @var{command}
@deftypefnx {} {} legend (@var{str1}, @var{str2}, @dots{})
@deftypefnx {} {} legend (@var{charmat})
@deftypefnx {} {} legend (@{@var{cellstr}@})
@deftypefnx {} {} legend (@dots{}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} legend (@var{hobjs}, @dots{})
@deftypefnx {} {} legend ("@var{command}")
@deftypefnx {} {} legend (@var{hax}, @dots{})
@deftypefnx {} {} legend (@var{hleg}, @dots{})
@deftypefnx {} {@var{hleg} =} 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.  When label names
might be confused with legend properties, or @var{command} arguments,
the labels should be protected by specifying them as a cell array of
strings.

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

If the first argument @var{hleg} is a legend handle, then operate on this
legend rather than the legend of the current axes.

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

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

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

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

@item @qcode{"toggle"}
  Toggle 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 @code{legend} function creates a graphics object which has various
properties that can be manipulated with @code{get}/@code{set}.
Alternatively, properties can be set directly when calling @code{legend} by
including @var{property}/@var{value} pairs.  If using this calling form, the
labels must be specified as a cell array of strings.  Graphics object
properties are documented in detail at @ref{Graphics Object Properties}.

Following is a subset of supported legend properties:
@c The following table is obtained by copying the output of
@c genpropdoc ("legend", "", {"autoupdate", "box", "location", "numcolumns", "orientation", "string", "textcolor"})

@table @asis

@item @code{autoupdate}: @qcode{"off"} | @{@qcode{"on"}@}
Control whether the number of legend items is updated automatically when
objects are added to (or deleted from) the peer axes.  For example:

@example
@group
## Create a single plot with its legend.
figure ();
plot (1:10);
legend ("Slope 1");
## Add another plot and specify its displayname so that
## the legend is correctly updated.
hold on;
plot ((1:10) * 2, "displayname", "Slope 2");
## Stop automatic updates for further plots.
legend ("autoupdate", "off");
plot ((1:10) * 3);
@end group
@end example

@item @code{box}: @qcode{"off"} | @{@qcode{"on"}@}
Control whether the legend has a surrounding box.

@item @code{location}: @qcode{"best"} | @qcode{"bestoutside"} |
@qcode{"east"} | @qcode{"eastoutside"} | @qcode{"none"} | @qcode{"north"} |
@{@qcode{"northeast"}@} | @qcode{"northeastoutside"} |
@qcode{"northoutside"} | @qcode{"northwest"}| @qcode{"northwestoutside"} |
@qcode{"south"} | @qcode{"southeast"} | @qcode{"southeastoutside"} |
@qcode{"southoutside"} | @qcode{"southwest"} | @qcode{"southwestoutside"} |
@qcode{"west"} | @qcode{"westoutside"}
Control the location of the legend.

@item @code{numcolumns}: scalar interger, def. @code{1}
Control the number of columns used in the layout of the legend items.
For example:

@example
@group
figure ();
plot (rand (30));
legend ("numcolumns", 3);
@end group
@end example

Setting @code{numcolumns} also forces the @code{numcolumnsmode} property
to be set to @qcode{"manual"}.

@item @code{orientation}: @qcode{"horizontal"} | @{@qcode{"vertical"}@}
Control whether the legend items are arranged vertically (column-wise) or
horizontally (row-wise).

@item @code{string}: string | cell array of strings
List of labels for the legend items.  For example:

@example
@group
figure ();
plot (rand (20));
## Let legend choose names automatically
hl = legend ();
## Selectively change some names
str = get (hl, "string");
str(1:5:end) = "Garbage";
set (hl, "string", str);
@end group
@end example

@item @code{textcolor}: colorspec, def. @code{[0   0   0]}
Control the color of the text strings for legend item.

@end table

The full list of supported legend specific properties can be found at
@ref{Legend Properties, , Legend Properties}.

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

The optional output value @var{hleg} is a handle to the legend object.

Implementation Note: The legend label text is either provided in the call to
@code{legend} or is taken from the @code{DisplayName} property of the
graphics objects.  Only data objects, such as line, patch, and surface, have
this property whereas axes, figures, etc.@: do not so they are never present
in a legend.  If no labels or @code{DisplayName} properties are available,
then the label text is simply @qcode{"data1"}, @qcode{"data2"}, @dots{},
@nospell{@qcode{"dataN"}}.

The legend @code{FontSize} property is initially set to 90% of the axes
@code{FontSize} to which it is attached.  Use @code{set} to override this
if necessary.
@end deftypefn


@c text scripts/plot/appearance/text.m
@anchor{XREFtext}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} text (@var{x}, @var{y}, @var{string})
@deftypefnx {} {} text (@var{x}, @var{y}, @var{z}, @var{string})
@deftypefnx {} {} text (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} text (@var{hax}, @dots{})
@deftypefnx {} {@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.

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

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

Example 1 : multi-line text via 3 different methods

@example
@group
text (0.5, 0.8, @{"Line 1", "Line 2"@})
text (0.5, 0.6, ["Line 1"; "Line 2"])
text (0.5, 0.4, "Line 1\nLine 2")
@end group
@end example

Example 2 : text at multiple locations

@example
@group
text ([0.2, 0.2], [0.8, 0.6], "Same text at two locations")
text ([0.4, 0.4], [0.8, 0.6], @{"Point 1 Text", "Point 2 text"@})
text ([0.6, 0.6], [0.8, 0.6], @{@{"Point 1 Line 1", "Point 1 Line 2@},
                               "Point 2 text"@})
@end group
@end example

Example 2 : adjust appearance using text properties

@example
@group
ht = text (0.5, 0.5, "Hello World", "fontsize", 20);
set (ht, "color", "red");
@end group
@end example

Programming Notes: The full list of properties is documented at
@ref{Text Properties}.

Any numeric entries in a cell array will be converted to text using
@code{sprintf ("%g")}.  For more precise control of the appearance convert
any numeric entries to strings using @code{num2str}, @code{sprintf}, etc.,
before calling @code{text}.
@xseealso{@ref{XREFgtext,,gtext}, @ref{XREFtitle,,title}, @ref{XREFxlabel,,xlabel}, @ref{XREFylabel,,ylabel}, @ref{XREFzlabel,,zlabel}}
@end deftypefn


@c xlabel scripts/plot/appearance/xlabel.m
@anchor{XREFxlabel}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} xlabel (@var{string})
@deftypefnx {} {} xlabel (@var{string}, @var{property}, @var{val}, @dots{})
@deftypefnx {} {} xlabel (@var{hax}, @dots{})
@deftypefnx {} {@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.

The full list of text object properties is documented at
@ref{Text Properties}.

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

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


@c ylabel scripts/plot/appearance/ylabel.m
@anchor{XREFylabel}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ylabel (@var{string})
@deftypefnx {} {} ylabel (@var{string}, @var{property}, @var{val}, @dots{})
@deftypefnx {} {} ylabel (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ylabel (@dots{})
Specify the string used to label the y-axis of the current axis.

If @var{hax} is specified then label the axis defined by @var{hax}.

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

The full list of text object properties is documented at
@ref{Text Properties}.

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

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


@c zlabel scripts/plot/appearance/zlabel.m
@anchor{XREFzlabel}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} zlabel (@var{string})
@deftypefnx {} {} zlabel (@var{string}, @var{property}, @var{val}, @dots{})
@deftypefnx {} {} zlabel (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} zlabel (@dots{})
Specify the string used to label the z-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.

The full list of text object properties is documented at
@ref{Text Properties}.

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

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


@c clabel scripts/plot/appearance/clabel.m
@anchor{XREFclabel}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} clabel (@var{c}, @var{h})
@deftypefnx {} {} clabel (@var{c}, @var{h}, @var{v})
@deftypefnx {} {} clabel (@var{c}, @var{h}, "manual")
@deftypefnx {} {} clabel (@var{c})
@deftypefnx {} {} clabel (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@var{hlabels} =} 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{hlabels} 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.

The full list of text object properties is documented at
@ref{Text Properties}.

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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} box
@deftypefnx {} {} box on
@deftypefnx {} {} box off
@deftypefnx {} {} box (@var{hax}, @dots{})
Control display of the axes 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
axes rather than the current axes returned by @code{gca}.
@xseealso{@ref{XREFaxis,,axis}, @ref{XREFgrid,,grid}}
@end deftypefn


@c grid scripts/plot/appearance/grid.m
@anchor{XREFgrid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} grid
@deftypefnx {} {} grid on
@deftypefnx {} {} grid off
@deftypefnx {} {} grid minor
@deftypefnx {} {} grid minor on
@deftypefnx {} {} grid minor off
@deftypefnx {} {} 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 axes rather than the current axes returned by @code{gca}.

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

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


@c colorbar scripts/plot/draw/colorbar.m
@anchor{XREFcolorbar}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} colorbar
@deftypefnx {} {} colorbar (@dots{}, @var{loc})
@deftypefnx {} {} colorbar (@var{delete_option})
@deftypefnx {} {} colorbar (@var{hcb}, @dots{})
@deftypefnx {} {} colorbar (@var{hax}, @dots{})
@deftypefnx {} {} colorbar (@dots{}, "peer", @var{hax}, @dots{})
@deftypefnx {} {} colorbar (@dots{}, "location", @var{loc}, @dots{})
@deftypefnx {} {} colorbar (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@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 @nospell{@var{loc}} determines the location of the
colorbar.  If present, it must be the last argument to @code{colorbar}.
Valid values for @nospell{@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{"off"}, @qcode{"delete"}, @qcode{"hide"}.

If the first argument @var{hax} is an axes handle, then the colorbar is
added to this axes, rather than the current axes returned by @code{gca}.
Alternatively, If the argument @qcode{"peer"} is given, then the following
argument is treated as the axes handle in which to add the colorbar.  The
@qcode{"peer"} calling syntax may be removed in the future and is not
recommended.

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 full list of properties is documented at
@ref{Axes Properties}.

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 object
with the @qcode{"tag"} property set to @qcode{"colorbar"}.  The created
object has the extra property @qcode{"location"} which controls the
positioning of the colorbar.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c annotation scripts/plot/appearance/annotation.m
@anchor{XREFannotation}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} annotation (@var{type})
@deftypefnx {} {} annotation ("line", @var{x}, @var{y})
@deftypefnx {} {} annotation ("arrow", @var{x}, @var{y})
@deftypefnx {} {} annotation ("doublearrow", @var{x}, @var{y})
@deftypefnx {} {} annotation ("textarrow", @var{x}, @var{y})
@deftypefnx {} {} annotation ("textbox", @var{pos})
@deftypefnx {} {} annotation ("rectangle", @var{pos})
@deftypefnx {} {} annotation ("ellipse", @var{pos})
@deftypefnx {} {} annotation (@dots{}, @var{prop}, @var{val})
@deftypefnx {} {} annotation (@var{hf}, @dots{})
@deftypefnx {} {@var{h} =} annotation (@dots{})
Draw annotations to emphasize parts of a figure.

You may build a default annotation by specifying only the @var{type}
of the annotation.

Otherwise you can select the type of annotation and then set its position
using either @var{x} and @var{y} coordinates for line-based annotations or a
position vector @var{pos} for others.  In either case, coordinates are
interpreted using the @qcode{"units"} property of the annotation object.
The default is @qcode{"normalized"}, which means the lower left hand corner
of the figure has coordinates @samp{[0 0]} and the upper right hand corner
@samp{[1 1]}.

If the first argument @var{hf} is a figure handle, then plot into this
figure, rather than the current figure returned by @code{gcf}.

Further arguments can be provided in the form of @var{prop}/@var{val} pairs
to customize the annotation appearance.

The optional return value @var{h} is a graphics handle to the created
annotation object.  This can be used with the @code{set} function to
customize an existing annotation object.

All annotation objects share two properties:

@itemize
@item @qcode{"units"}: the units in which coordinates are interpreted.@*
Its value may be one of @qcode{"centimeters"} | @qcode{"characters"} |
@qcode{"inches"} | @qcode{"@{normalized@}"} | @qcode{"pixels"} |
@qcode{"points"}.

@item @qcode{"position"}: a four-element vector [x0 y0 width height].@*
The vector specifies the coordinates (x0,y0) of the origin of the annotation
object, its width, and its height.  The width and height may be negative,
depending on the orientation of the object.

@end itemize

Valid annotation types and their specific properties are described
below:

@table @asis
@item @qcode{"line"}
Constructs a line.  @var{x} and @var{y} must be two-element vectors
specifying the x and y coordinates of the two ends of the line.

The line can be customized using @qcode{"linewidth"}, @qcode{"linestyle"},
and @qcode{"color"} properties the same way as for @code{line} objects.

@item @qcode{"arrow"}
Construct an arrow.  The second point in vectors @var{x} and @var{y}
specifies the arrowhead coordinates.

Besides line properties, the arrowhead can be customized using
@qcode{"headlength"}, @qcode{"headwidth"}, and @qcode{"headstyle"}
properties.  Supported values for @qcode{"headstyle"} property are:
[@qcode{"diamond"} | @qcode{"ellipse"} | @qcode{"plain"} |
@qcode{"rectangle"} | @qcode{"vback1"} | @qcode{"@{vback2@}"} |
@qcode{"vback3"}]

@item @qcode{"doublearrow"}
Construct a double arrow.  Vectors @var{x} and @var{y} specify the
arrowhead coordinates.

The line and the arrowhead can be customized as for arrow annotations, but
some property names are duplicated:
@qcode{"head1length"}/@qcode{"head2length"},
@qcode{"head1width"}/@qcode{"head2width"}, etc.  The index 1 marks the
properties of the arrowhead at the first point in @var{x} and @var{y}
coordinates.

@item @qcode{"textarrow"}
Construct an arrow with a text label at the opposite end from the arrowhead.

Use the @qcode{"string"} property to change the text string.
The line and the arrowhead can be customized as for arrow annotations, and
the text can be customized using the same properties as @code{text} graphics
objects.  Note, however, that some text property names are prefixed with
"text" to distinguish them from arrow properties:
@qcode{"textbackgroundcolor"}, @qcode{"textcolor"},
@qcode{"textedgecolor"}, @qcode{"textlinewidth"},
@qcode{"textmargin"}, @qcode{"textrotation"}.

@item @qcode{"textbox"}
Construct a box with text inside.  @var{pos} specifies the
@qcode{"position"} property of the annotation.

Use the @qcode{"string"} property to change the text string.
You may use @qcode{"backgroundcolor"}, @qcode{"edgecolor"},
@qcode{"linestyle"}, and @qcode{"linewidth"} properties to customize
the box background color and edge appearance.  A limited set of @code{text}
objects properties are also available; Besides @qcode{"font@dots{}"}
properties, you may also use @qcode{"horizontalalignment"} and
@qcode{"verticalalignment"} to position the text inside the box.

Finally, the @qcode{"fitboxtotext"} property controls the actual extent of
the box.  If @qcode{"on"} (the default) the box limits are fitted to the
text extent.

@item @qcode{"rectangle"}
Construct a rectangle.  @var{pos} specifies the @qcode{"position"} property
of the annotation.

You may use @qcode{"facecolor"}, @qcode{"color"}, @qcode{"linestyle"}, and
@qcode{"linewidth"} properties to customize the rectangle background color
and edge appearance.

@item @qcode{"ellipse"}
Construct an ellipse.  @var{pos} specifies the @qcode{"position"} property
of the annotation.

See @qcode{"rectangle"} annotations for customization.
@end table

@xseealso{@ref{XREFxlabel,,xlabel}, @ref{XREFylabel,,ylabel}, @ref{XREFzlabel,,zlabel}, @ref{XREFtitle,,title}, @ref{XREFtext,,text}, @ref{XREFgtext,,gtext}, @ref{XREFlegend,,legend}, @ref{XREFcolorbar,,colorbar}}
@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 row-major order
(left to right, top to bottom).  After plotting a sine wave, the next call to
subplot activates the second subplot area, but does not re-partition the
figure.

@c subplot scripts/plot/util/subplot.m
@anchor{XREFsubplot}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} subplot (@var{rows}, @var{cols}, @var{index})
@deftypefnx {} {} subplot (@var{rows}, @var{cols}, @var{index}, @var{hax})
@deftypefnx {} {} subplot (@var{rcn})
@deftypefnx {} {} subplot (@var{hax})
@deftypefnx {} {} subplot (@dots{}, "align")
@deftypefnx {} {} subplot (@dots{}, "replace")
@deftypefnx {} {} subplot ("position", @var{pos})
@deftypefnx {} {} subplot (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@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 an axes handle @var{hax} is provided after the (@var{rows}, @var{cols},
@var{index}) arguments, the corresponding axes is turned into a
subplot.

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

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

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

If the option @qcode{"replace"} is given then the subplot axes will be
reset, rather than just switching the current axes 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.
The full list of properties is documented at @ref{Axes Properties}.

Any previously existing axes that would be (partly) covered by the newly
created axes are deleted.

If the output @var{hax} is requested, subplot returns the axes handle for
the subplot.  This is useful for modifying the properties of a subplot
using @code{set}.

Under some circumstances, @code{subplot} might not be able to identify axes
that it could re-use and might replace them.  If @code{subplot} axes
should be referenced repeatedly, consider creating and storing their axes
handles beforehand instead of calling @code{subplot} repeatedly for the same
position.

Example:

@example
@group
x = 1:10;
y = rand (16, 10);
for i_plot = 1:4
  hax(i_plot) = subplot (2, 2, i_plot);
  hold (hax(i_plot), "on");
  grid (hax(i_plot), "on");
endfor
for i_loop = 1:2
  for i_plot = 1:4
    iy = (i_loop - 1)*4 + i_plot;
    plotyy (hax(i_plot), x,y(iy,:), x,y(iy+1,:));
  endfor
 endfor
@end group
@end example

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} figure
@deftypefnx {} {} figure @var{n}
@deftypefnx {} {} figure (@var{n})
@deftypefnx {} {} figure (@dots{}, "@var{property}", @var{value}, @dots{})
@deftypefnx {} {@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.

Programming Note: The full list of properties is documented at
@ref{Figure Properties}.
@xseealso{@ref{XREFaxes,,axes}, @ref{XREFgcf,,gcf}, @ref{XREFshg,,shg}, @ref{XREFclf,,clf}, @ref{XREFclose,,close}}
@end deftypefn


@node Manipulation of Plot Objects
@subsection Manipulation of Plot Objects
@cindex plotting, object manipulation

@c pan scripts/plot/util/pan.m
@anchor{XREFpan}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} pan
@deftypefnx {} {} pan on
@deftypefnx {} {} pan off
@deftypefnx {} {} pan xon
@deftypefnx {} {} pan yon
@deftypefnx {} {} pan (@var{hfig}, @var{option})
Control the interactive panning mode of a figure in the GUI.

Given the option @qcode{"on"} or @qcode{"off"}, set the interactive
pan mode on or off.

With no arguments, toggle the current pan mode on or off.

Given the option @qcode{"xon"} or @qcode{"yon"}, enable pan mode
for the x or y axis only.

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

@xseealso{@ref{XREFrotate3d,,rotate3d}, @ref{XREFzoom,,zoom}}
@end deftypefn


@c rotate scripts/plot/util/rotate.m
@anchor{XREFrotate}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} rotate (@var{h}, @var{direction}, @var{alpha})
@deftypefnx {} {} rotate (@dots{}, @var{origin})
Rotate the plot object @var{h} through @var{alpha} degrees around the line
with direction @var{direction} and origin @var{origin}.

The default value of @var{origin} is the center of the axes object that is
the parent of @var{h}.

If @var{h} is a vector of handles, they must all have the same parent axes
object.

Graphics objects that may be rotated are lines, surfaces, patches, and
images.
@end deftypefn


@c rotate3d scripts/plot/util/rotate3d.m
@anchor{XREFrotate3d}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} rotate3d
@deftypefnx {} {} rotate3d on
@deftypefnx {} {} rotate3d off
@deftypefnx {} {} rotate3d (@var{hfig}, @var{option})
Control the interactive 3-D rotation mode of a figure in the GUI.

Given the option @qcode{"on"} or @qcode{"off"}, set the interactive
rotate mode on or off.

With no arguments, toggle the current rotate mode on or off.

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

@xseealso{@ref{XREFpan,,pan}, @ref{XREFzoom,,zoom}}
@end deftypefn


@c zoom scripts/plot/util/zoom.m
@anchor{XREFzoom}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} zoom
@deftypefnx {} {} zoom (@var{factor})
@deftypefnx {} {} zoom on
@deftypefnx {} {} zoom off
@deftypefnx {} {} zoom xon
@deftypefnx {} {} zoom yon
@deftypefnx {} {} zoom out
@deftypefnx {} {} zoom reset
@deftypefnx {} {} zoom (@var{hfig}, @var{option})
Zoom the current axes object or control the interactive zoom mode of a
figure in the GUI.

Given a numeric argument greater than zero, zoom by the given factor.  If
the zoom factor is greater than one, zoom in on the plot.  If the factor
is less than one, zoom out.  If the zoom factor is a two- or three-element
vector, then the elements specify the zoom factors for the x, y, and z
axes respectively.

Given the option @qcode{"on"} or @qcode{"off"}, set the interactive zoom
mode on or off.

With no arguments, toggle the current zoom mode on or off.

Given the option @qcode{"xon"} or @qcode{"yon"}, enable zoom mode for the
x or y-axis only.

Given the option @qcode{"out"}, zoom to the initial zoom setting.

Given the option @qcode{"reset"}, store the current zoom setting so that
@code{zoom out} will return to this zoom level.

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

@xseealso{@ref{XREFpan,,pan}, @ref{XREFrotate3d,,rotate3d}}
@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} drawnow ()
@deftypefnx {} {} drawnow ("expose")
@deftypefnx {} {} drawnow (@var{term}, @var{file}, @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.
@xseealso{@ref{XREFrefresh,,refresh}}
@end deftypefn


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

@c refresh scripts/plot/util/refresh.m
@anchor{XREFrefresh}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} refresh ()
@deftypefnx {} {} 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.
@xseealso{@ref{XREFdrawnow,,drawnow}}
@end deftypefn


Normally, high-level plot functions like @code{plot} or @code{mesh} call
@code{newplot} to determine whether the state of the target axes should be
initialized (the default) or if subsequent plots should be drawn on top of
previous ones.  To have two plots drawn over one another, use the @code{hold}
function or manually change the axes @ref{XREFaxesnextplot, ,nextplot}
property.  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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} newplot ()
@deftypefnx {} {} newplot (@var{hfig})
@deftypefnx {} {} newplot (@var{hax})
@deftypefnx {} {@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 axes 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 Axes 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 axes 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
axes and reset all axes 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 axes.
@end deftypefn


@c hold scripts/plot/util/hold.m
@anchor{XREFhold}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} hold
@deftypefnx {} {} hold on
@deftypefnx {} {} hold off
@deftypefnx {} {} 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.  Line color and line style are advanced for each new plot
added.

@item hold all (deprecated)
Equivalent to @code{hold on}.

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

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


@c ishold scripts/plot/util/ishold.m
@anchor{XREFishold}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tf} =} ishold
@deftypefnx {} {@var{tf} =} ishold (@var{hax})
@deftypefnx {} {@var{tf} =} 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.
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} clf
@deftypefnx {} {} clf reset
@deftypefnx {} {} clf (@var{hfig})
@deftypefnx {} {} clf (@var{hfig}, "reset")
@deftypefnx {} {@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.
@xseealso{@ref{XREFcla,,cla}, @ref{XREFclose,,close}, @ref{XREFdelete,,delete}, @ref{XREFreset,,reset}}
@end deftypefn


@c cla scripts/plot/util/cla.m
@anchor{XREFcla}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} cla
@deftypefnx {} {} cla reset
@deftypefnx {} {} cla (@var{hax})
@deftypefnx {} {} cla (@var{hax}, "reset")
Clear the current or specified (@var{hax}) axes object.

@code{cla} operates by deleting child graphic objects with visible
handles (@code{HandleVisibility} = @qcode{"on"}).  This typically clears the
axes of any visual objects, but leaves in place axes limits, tick marks and
labels, camera view, etc.  In addition, the automatic coloring and styling
of lines is reset by changing the axes properties @code{ColorOrderIndex},
@code{LinestyleOrderIndex} to 1.

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

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


@c shg scripts/plot/util/shg.m
@anchor{XREFshg}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} shg
Show the graph window.

This function makes the current figure visible, and places it on top of
of all other plot windows.

Programming Note: @code{shg} is equivalent to @code{figure (gcf)} assuming
that a current figure exists.
@xseealso{@ref{XREFfigure,,figure}, @ref{XREFdrawnow,,drawnow}, @ref{XREFgcf,,gcf}}
@end deftypefn


@c delete scripts/miscellaneous/delete.m
@anchor{XREFdelete}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} delete @var{file}
@deftypefnx {} {} delete @var{file1} @var{file2} @dots{}
@deftypefnx {} {} delete (@var{file})
@deftypefnx {} {} delete (@var{file1}, @var{file2}, @dots{})
@deftypefnx {} {} delete (@var{handle})
Delete the named file or graphics handle.

@var{file} may contain globbing patterns such as @samp{*}.  Multiple files
to be deleted may be specified in the same function call.

@var{handle} may be a scalar or vector of graphic handles to delete.

Programming Note: Deleting graphics objects is the proper way to remove
features from a plot without clearing the entire figure.
@xseealso{@ref{XREFclf,,clf}, @ref{XREFcla,,cla}, @ref{XREFunlink,,unlink}, @ref{XREFrmdir,,rmdir}}
@end deftypefn


@c close scripts/plot/util/close.m
@anchor{XREFclose}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} close
@deftypefnx {} {} close (@var{h})
@deftypefnx {} {} close @var{figname}
@deftypefnx {} {} close all
@deftypefnx {} {} close all hidden
@deftypefnx {} {} close all force
@deftypefnx {} {@var{status} =} close (@dots{})
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}.  The figure to
close may also be specified by name @var{figname} which is matched against
the @qcode{"Name"} property of all figures.

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

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

If the additional argument @qcode{"force"} is given then figures are closed
even when @qcode{"closerequestfcn"} has been altered to prevent closing the
window.

If the optional output @var{status} is requested then Octave returns 1 if
the figure windows were closed successfully.

Implementation Note: @code{close} operates by making the handle @var{h} the
current figure, and then calling the function specified by the
@qcode{"closerequestfcn"} property of the 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.

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


@c closereq scripts/plot/util/closereq.m
@anchor{XREFclosereq}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} 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.
@xseealso{@ref{XREFclose,,close}, @ref{XREFdelete,,delete}}
@end deftypefn


@node Use of the "interpreter" Property
@subsection Use of the "interpreter" Property

@code{text} (such as titles, labels, legend item) and @code{axes} objects
feature an @ref{XREFtextinterpreter,,@qcode{"interpreter"}} and a
@ref{XREFaxesticklabelinterpreter,,@qcode{"ticklabelinterpreter"}} property
respectively.  It determines the manner in which special control sequences in
the text are rendered.

The interpreter property can take three values: @qcode{"none"}, @qcode{"tex"},
@qcode{"latex"}.

@menu
* "none" interpreter::
* "tex" interpreter::
* "latex" interpreter::
@end menu

@node "none" interpreter
@subsubsection "none" interpreter

If the interpreter is set to @qcode{"none"} then no special
rendering occurs---the displayed text is a verbatim copy of the specified text.

@node "tex" interpreter
@subsubsection "tex" interpreter

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

Besides special glyphs, 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 codes may be used in conjunction with the @{ and @} characters to limit
the change to a 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 bold font.  Note that to
avoid having Octave interpret the backslash character in the strings,
the strings themselves should be in single quotes.

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

@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

The color of the text may also be changed inline using either a string (e.g.,
"red") or numerically with a Red-Green-Blue (RGB) specification (e.g.,
[1 0 0], also red).

@multitable @columnfractions .1 .4 .6 .1
@item @tab \color@{@var{color}@} @tab Specify the color as a string @tab
@item @tab \color[rgb]@{@var{R} @var{G} @var{B}@} @tab Specify the color
numerically @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 @w{@{ @}}@ pair is
superscripted or subscripted.  Without the @w{@{ @}}@ pair, only the character
immediately following the @qcode{'^'} or @qcode{'_'} is changed.

@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

@strong{Caution: Degree Symbol}
@cindex Degree Symbol

Conformance to both @TeX{} and @sc{matlab} with respect to the @code{\circ}
symbol is impossible.  While @TeX{} translates this symbol to
@w{Unicode 2218}@ (U+2218), @sc{matlab} maps this to @w{Unicode 00B0}@ (U+00B0)
instead.  Octave has chosen to follow the @TeX{} specification, but has added
the additional symbol @code{\deg} which maps to the degree symbol (U+00B0).

@node "latex" interpreter
@subsubsection "latex" interpreter

The @qcode{"latex"} interpreter only works if an external @LaTeX{} tool chain
is present.  Three binaries are needed: @code{latex}, @code{dvipng}, and
@code{dvisvgm}.  If those binaries are installed but not on the path, one can
still provide their respective path using the following environment variables:
@w{@env{OCTAVE_LATEX_BINARY}}, @w{@env{OCTAVE_DVIPNG_BINARY}}, and
@w{@env{OCTAVE_DVISVG_BINARY}}.

Note that Octave does not parse or validate the text strings when in
@qcode{"latex"} mode---it is the responsibility of the programmer to generate
valid strings which may include wrapping sections that should appear in Math
mode with @qcode{'$'} characters.
See, for example, @url{https://www.latex-project.org/help/documentation/} for
documentation about @LaTeX{} typesetting.

For debugging purpose, a convenience environment variable,
@w{@env{OCTAVE_LATEX_DEBUG_FLAG}}, can be set to trigger more verbose output
when Octave fails to have a given text compiled by an external @LaTeX{} engine.
For example, @qcode{"x^2"} is not a valid @LaTeX{} string and the following
example should fail

@example
@group
setenv ("OCTAVE_LATEX_DEBUG_FLAG", "1")
x = 1:10;
plot (x, x.^2)
title ("x^2", "interpreter", "latex")
@end group
@end example

Searching the terminal output you should find some helpful info about the
origin of the failure:

@example
@group
...
No file default.aux.
! Missing $ inserted.
<inserted text>
                $
l.6 x^
      2
! Missing $ inserted.
...
@end group
@end example

If no usable @LaTeX{} tool chain is found at the first text rendering, using
the @qcode{"latex"} interpreter is equivalent to @qcode{"none"}.

@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 your 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 foo.pdf
@end example

@noindent
saves the current figure to a Portable Document encapsulated PostScript file
called @file{foo.pdf}.

The current graphic toolkits produce very similar graphic displays, but the
interpreters differ in their capability to display unusual text and in their
ability to print such text.  In general, the @qcode{"tex"} interpreter
(default) is the best all-around performer for both on-screen display and
printing.  However, for the reproduction of complicated text formulas the
@qcode{"latex"} interpreter is preferred.  The @qcode{"none"} interpreter
prints text verbatim (exactly as it appears) which is very portable, but there
is no support for bold, italic, superscripts, subscripts, Greek letters, etc.

When printing with the @option{-painters} renderer, the default for all vector
formats, two options may be considered:

@itemize @bullet
@item
Use the @option{-svgconvert} option to allow for rendering @LaTeX{} formulas.
Note that the glyph are rendered as path and the original textual info are
lost.

@item
Use one of the @option{-d*latex*} devices to produce a .tex file (plus
supporting .eps or .pdf files) to be further processed by an external @LaTeX{}
engine.  Note that the @code{print} function will first set the interpreter of
all strings to @qcode{"latex"}, which means all strings must be valid @LaTeX{}
strings.
@end itemize

A complete example showing the capabilities of text printing using the
@option{-dpdflatexstandalone} option is:

@example
@group
x = 0:0.01:3;
hf = figure ();
plot (x, erf (x));
hold on;
plot (x, x, "r");
axis ([0, 3, 0, 1]);
text (0.65, 0.6175, ...
      ['$\displaystyle\leftarrow x = @{2 \over \sqrt@{\pi@}@}' ...
       '\int_@{0@}^@{x@} e^@{-t^2@} dt = 0.6175$'],
      "interpreter", "latex");
xlabel ("x");
ylabel ("erf (x)");
title ("erf (x) with text annotation");
print (hf, "plot15_7", "-dpdflatexstandalone");
system ("pdflatex plot15_7");
open plot15_7.pdf
@end group
@end example

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

@float Figure,fig:extendedtext
@center @image{extended,4in}
@caption{Example of inclusion of text with use of @option{-dpdflatexstandalone}}
@end float
@end ifnotinfo

@c print scripts/plot/util/print.m
@anchor{XREFprint}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} print ()
@deftypefnx {} {} print (@var{options})
@deftypefnx {} {} print (@var{filename}, @var{options})
@deftypefnx {} {} print (@var{hfig}, @dots{})
@deftypefnx {} {@var{RGB} =} print (@qcode{"-RGBImage"}, @dots{})
Format a figure for printing and either save it to a file, send it to a
printer, or return an RGB image.

@var{filename} defines the name of the output file.  If the filename has
no suffix then one is inferred from the specified device and appended to the
filename.  When neither a filename nor the @qcode{"-RGBImage"} option is
present, the output is sent to the printer.  The various options and
filename arguments may be given in any order, except for the figure handle
argument @var{hfig} which must be first if it is present.

Example: Print to a file using PDF and JPEG formats.

@example
@group
figure (1);
clf ();
surf (peaks);
print figure1.pdf    # The extension specifies the format
print -djpg figure1  # Will produce "figure1.jpg" file
@end group
@end example

If the first argument is a handle @var{hfig} to a figure object then it
specifies the figure to print.  By default, the current figure returned
by @code{gcf} is printed.

For outputs to paged formats, for example, PostScript and PDF, the page size
is specified by the figure's @code{papersize} property together with the
@code{paperunits} property.  The location and size of the plot 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.

For non-page formats---for example, image formats like JPEG---the width and
height of the output are specified by the figure's @code{paperposition(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.

Example: Print figure 1.

@example
@group
figure (1);
clf ();
surf (peaks);
figure (2);
print -f1 figure1.pdf
## Equivalent functional form:
print (1, "figure1.pdf")
@end group
@end example

@item -P@var{printer}
  Set the @var{printer} name to which the plot is sent if no @var{filename}
is specified.

Example: Print to printer named PS_printer using PostScript format.

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

@item -RGBImage
  Return an M-by-N-by-3 RGB image of the figure.  The size of the image
depends on the formatting options.  This is similar to taking a screen
capture of the plot, but formatting options may be changed such as the
resolution or monochrome/color.

Example: Get the pixels of a figure image.

@example
@group
clf ();
surf (peaks);
@var{rgb} = print ("-RGBImage");
@end group
@end example

@item  -image | -opengl
@itemx -vector | -painters
  Specifies whether the pixel-based renderer (@option{-image} or
@option{-opengl}) or vector-based renderer (@option{-vector} or
@option{-painters}) is used.  This is equivalent to changing the figure's
@qcode{"Renderer"} property.  When the figure
@nospell{@qcode{"RendererMode"}} property is @qcode{"auto"} (the default)
Octave will use the @qcode{"opengl"} renderer for raster formats (e.g.,
JPEG) and @qcode{"painters"} for vector formats (e.g., PDF)@.  These options
are only supported for the "qt" graphics toolkit.

@item  -svgconvert (default)
@itemx -nosvgconvert
  When using the @option{-painters} renderer, this enables or disables the
SVG based backend toolchain with enhanced characteristics:

@table @asis
@item Font handling:
For interpreters "none" and "tex", the actual font is embedded in the output
file which allows for printing arbitrary characters and fonts in all vector
formats.

Strings using the @qcode{"latex"} interpreter, are rendered using path
objects.  This looks good but note that textual info (font,
characters@dots{}) are lost.

@item Output Simplification:
By default, the option @option{-painters} renders patch and surface objects
using assemblies of triangles.  This may lead to anti-aliasing artifacts
when viewing the file.  The @option{-svgconvert} option reconstructs
polygons in order to avoid those artifacts (particularly for 2-D figures).

@item Transparency:
Allows for printing transparent graphics objects in PDF format.
For PostScript formats the presence of any transparent object will cause the
output to be rasterized.
@end table

Caution: If Octave was built against Qt version earlier than 5.13,
@option{-svgconvert} may lead to inaccurate rendering of image objects.

@item  -polymerge
@itemx -nopolymerge
@itemx -polymerge-all
  When using the SVG based backend @option{-svgconvert}, faces are rendered
as triangles.  In some cases, some viewers might display fine lines where
those triangles share an edge.  These options control whether all triangles
that share edges are merged into polygons (@option{-polymerge-all} which
might take some time for graphics consisting of many triangles -- including
line markers), only consecutive polygons are merged (@option{-polymerge}),
or no triangles are merged at all (@option{-no-polymerge}).  By default,
only consecutive triangles sharing an edge are merged, unless the printed
figure contains patch or surface graphics objects in which case all
triangles that are sharing an edge are merged.

@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  -fillpage
@itemx -bestfit
  When using a page-based format (PDF, PostScript, printer) ignore the
@qcode{"paperposition"} property and have the plot occupy the entire page.
The option @option{-fillpage} will stretch the plot to occupy the page with
0.25 inch margins all around.  The option @option{-bestfit} will expand the
plot to take up as much room as possible on the page @strong{without}
distorting the original aspect ratio of the plot.

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

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

@item -noui
  Don't print uicontrol objects such as pushbuttons which may overlay the
plot.  This is the default behavior and it is not possible to include
uicontrol objects in the output without using an external screen capture
tool.

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

Example: high resolution raster output.

@example
@group
clf ();
surf (peaks (), "facelighting", "gouraud");
light ();
print ("-r600", "lit_peaks.png");
@end group
@end example

@item -S@var{xsize},@var{ysize}
  Plot size in pixels for raster formats including PNG, JPEG, PNG, and
@emph{unusually} SVG@.  For all vector formats, including PDF, PS, and EPS,
the plot size is specified in points.  This option is equivalent to changing
the width and height of the output by setting the figure property
@code{paperposition(3:4)}.  When using the command form of the print
function you must quote the @var{xsize},@var{ysize} option to prevent the
Octave interpreter from recognizing the embedded comma (',').  For example,
by writing @w{"-S640,480"}.

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

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

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

@item -metafile
    Provide a metafile preview.

@item -pict
    Provide a pict preview.

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

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

@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: fig, etc.

@item -d@var{device}
  The available output format is specified by the option @var{device}, and
is one of the following (devices marked with a @qcode{'*'} are only
available with the Gnuplot toolkit):

Vector Formats

@table @code
@item svg
    Scalable Vector Graphics.

@item  pdf
@itemx pdfcrop
    Portable Document Format.  The @code{pdf} device formats the figure for
printing on paper.  The size of the surrounding page and the position of the
figure inside the page are defined by the
@ref{XREFfigurepaperorientation,, paper* figure properties}.

Use @code{pdfcrop} if you don't want the surrounding page.

Caution: with @option{-nosvgconvert} option, PDF inherits the same
limitations as PostScript (limited set of fonts and lack of transparency).

@item  eps(2)
@itemx epsc(2)
    Encapsulated PostScript (level 1 and 2, mono and color).

The OpenGL-based graphics toolkits always generate PostScript level 3.0.
They have limited support for text unless using the @option{-svgconvert}
option (the default).
Limitations include using only ASCII characters (e.g., no Greek letters)
and support for just three base PostScript fonts: Helvetica (the default),
Times, or Courier.  Any other font will be replaced by Helvetica.

@item  ps(2)
@itemx psc(2)
    Same as @code{eps} except that the figure is formatted for printing on
paper.  The size of the surrounding page and position of the figure inside
the page are defined by the
@ref{XREFfigurepaperorientation,, paper* figure properties}.

@item  pslatex
@itemx epslatex
@itemx pdflatex
@itemx pslatexstandalone
@itemx epslatexstandalone
@itemx pdflatexstandalone
    Generate a @LaTeX{} file @file{@var{filename}.tex} for the text portions
of a plot and a file @file{@var{filename}.(ps|eps|pdf)} for the remaining
graphics.  The graphics file suffix .ps|eps|pdf is determined by the
specified device type.  The @LaTeX{} file produced by the @samp{standalone}
option can be processed directly by @LaTeX{}.  The file generated without
the @samp{standalone} option is intended to be included from another
@LaTeX{} document.  In either case, the @LaTeX{} file contains an
@code{\includegraphics} command so that the generated graphics file is
automatically included when the @LaTeX{} file is processed.  The text that
is written to the @LaTeX{} file contains the strings @strong{exactly} as
they were specified in the plot.  If any special characters of the @TeX{}
mode interpreter were used, the file must be edited before @LaTeX{}
processing.  Specifically, the special characters must be enclosed with
dollar signs @w{(@code{$ @dots{} $})}, and other characters that are
recognized by @LaTeX{} may also need editing (e.g., braces).  The
@samp{pdflatex} device, and any of the @samp{standalone} formats, are not
available with the Gnuplot toolkit.

@item  epscairo*
@itemx pdfcairo*
@itemx epscairolatex*
@itemx pdfcairolatex*
@itemx epscairolatexstandalone*
@itemx pdfcairolatexstandalone*
    Generate output with Cairo renderer.  The devices @code{epscairo} and
@code{pdfcairo} are synonymous with the @code{epsc} device.  The @LaTeX{}
variants generate a @LaTeX{} file, @file{@var{filename}.tex}, for the text
portions of a plot, and an image file, @file{@var{filename}.(eps|pdf)}, for
the graph portion of the plot.  The @samp{standalone} variants behave as
described for @samp{epslatexstandalone} above.

@item canvas*
    Javascript-based drawing on an HTML5 canvas viewable in a web browser.

@item  emf
@itemx meta
    Microsoft Enhanced Metafile

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

@item  latex*
@itemx eepic*
@LaTeX{} picture environment and extended picture environment.

@item  tikz
@itemx tikzstandalone*
    Generate a @LaTeX{} file using PGF/TikZ format.  The OpenGL-based
toolkits create a PGF file while Gnuplot creates a TikZ file.  The
@samp{tikzstandalone} device produces a @LaTeX{} document which includes the
TikZ file.

@end table

Raster Formats

@table @code
@item png
    Portable Network Graphics

@item  jpg
@itemx jpeg
    JPEG image

@item  tif
@itemx tiff
@itemx tiffn
    TIFF image with LZW compression (@nospell{tif}, tiff) or uncompressed
(@nospell{tiffn}).

@item gif
    GIF image

@item pbm
    PBMplus

@item dumb*
    ASCII art

@end table

  If the device is omitted, it is inferred from the file extension,
or if there is no filename then 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 pcx24b
    24-bit color PCX file format

@item ppm
    Portable Pixel Map file format
@end table

  For a complete list of available formats and devices type
@kbd{system ("gs -h")}.

  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 -G@var{ghostscript_command}
  Specify the command for calling Ghostscript.  For Unix the default is
@qcode{"gs"} and for Windows it is @qcode{"gswin32c"}.

@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 are 4 and 1
respectively.  Allowed values for @var{N} are 1, 2, or 4.

@item -no-append-file-extension
  With this option, @var{filename} is used verbatim.  That means no file
extension matching the file format is appended automatically.
@end table

@xseealso{@ref{XREFsaveas,,saveas}, @ref{XREFgetframe,,getframe}, @ref{XREFsavefig,,savefig}, @ref{XREFhgsave,,hgsave}, @ref{XREForient,,orient}, @ref{XREFfigure,,figure}}
@end deftypefn


@c saveas scripts/plot/util/saveas.m
@anchor{XREFsaveas}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} saveas (@var{h}, @var{filename})
@deftypefnx {} {} saveas (@var{h}, @var{filename}, @var{fmt})
Save graphics object @var{h} to the file @var{filename} in graphics format
@var{fmt}.

If @var{h} is the handle to a figure object, that figure object is saved.
If @var{h} is the handle to a different graphics object, the figure
containing that graphics object is saved.

All device formats accepted by @code{print} may be used.  Common formats
are:

@table @code

@item ofig
    Octave figure file format (default)

@item mfig
    Two files: Octave m-file @file{filename.m} containing code
    to open Octave figure file @file{filename.ofig}

@item ps
    PostScript

@item eps
    Encapsulated PostScript

@item pdf
    Portable Document Format

@item jpg
    JPEG Image

@item png
    Portable Network Graphics image

@item emf
    Enhanced MetaFile

@item tif
    TIFF Image, compressed

@end table

If @var{fmt} is omitted it is extracted from the extension of
@var{filename}.  The default format when there is no extension is
@qcode{"ofig"}.

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

@xseealso{@ref{XREFprint,,print}, @ref{XREFsavefig,,savefig}, @ref{XREFhgsave,,hgsave}, @ref{XREForient,,orient}}
@end deftypefn


@c orient scripts/plot/appearance/orient.m
@anchor{XREForient}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} orient (@var{orientation})
@deftypefnx {} {} orient (@var{hfig}, @var{orientation})
@deftypefnx {} {@var{orientation} =} orient ()
@deftypefnx {} {@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}.
@xseealso{@ref{XREFprint,,print}, @ref{XREFsaveas,,saveas}}
@end deftypefn


@code{print} and @code{saveas} are used when work on a plot has finished
and the output must be in a publication-ready format.  During intermediate
stages it is often better to save the graphics object and all of its
associated information so that changes---to colors, axis limits, marker styles,
etc.---can be made easily from within Octave.  The @code{hgsave}/@code{hgload}
commands can be used to save and re-create a graphics object.

@c hgsave scripts/plot/util/hgsave.m
@anchor{XREFhgsave}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} hgsave (@var{filename})
@deftypefnx {} {} hgsave (@var{h}, @var{filename})
@deftypefnx {} {} hgsave (@var{h}, @var{filename}, @var{fmt})
Save the graphics handle(s) @var{h} to the file @var{filename} in the format
@var{fmt}.

If unspecified, @var{h} is the current figure as returned by @code{gcf}.

When @var{filename} does not have an extension the default filename
extension @file{.ofig} will be appended.

If present, @var{fmt} must be one of the following:

@itemize @bullet
@item @option{-binary}, @option{-float-binary}

@item @option{-hdf5}, @option{-float-hdf5}

@item @option{-V7}, @option{-v7}, @option{-7}, @option{-mat7-binary}

@item @option{-V6}, @option{-v6}, @option{-6}, @option{-mat6-binary}

@item @option{-text}

@item @option{-zip}, @option{-z}
@end itemize

The default format is @option{-binary} to minimize storage.

Programming Note: When producing graphics for final publication use
@code{print} or @code{saveas}.  When it is important to be able to continue
to edit a figure as an Octave object, use @code{hgsave}/@code{hgload}.
@xseealso{@ref{XREFhgload,,hgload}, @ref{XREFhdl2struct,,hdl2struct}, @ref{XREFsavefig,,savefig}, @ref{XREFsaveas,,saveas}, @ref{XREFprint,,print}}
@end deftypefn


@c hgload scripts/plot/util/hgload.m
@anchor{XREFhgload}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} hgload (@var{filename})
@deftypefnx {} {[@var{h}, @var{old_prop}] =} hgload (@var{filename}, @var{prop_struct})
Load the graphics objects in @var{filename} into a vector of graphics
handles @var{h}.

If @var{filename} has no extension, Octave will try to find the file with
and without the default extension @file{.ofig}.

If provided, the elements of structure @var{prop_struct} will be used to
override the properties of top-level objects stored in @var{filename}, and
the saved values from @var{filename} will be stored in @var{old_prop}.
@var{old_prop} is a cell array matching the size of @var{h}; each cell
contains a structure of the existing property names and values before being
overridden.

@xseealso{@ref{XREFopenfig,,openfig}, @ref{XREFhgsave,,hgsave}, @ref{XREFstruct2hdl,,struct2hdl}}
@end deftypefn


@c openfig scripts/plot/util/openfig.m
@anchor{XREFopenfig}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} openfig
@deftypefnx {} {} openfig (@var{filename})
@deftypefnx {} {} openfig (@dots{}, @var{copies})
@deftypefnx {} {} openfig (@dots{}, @var{visibility})
@deftypefnx {} {@var{h} =} openfig (@dots{})
Read saved figure window(s) from @var{filename} and return graphics
handle(s) @var{h}.

By default, @var{filename} is @qcode{"Untitled.fig"}.  If a full path is not
specified, the file opened will be the first one encountered in the load
path.  If @var{filename} is not found and does not have an extension, a
search will take place for the first file in the load path with extension
@qcode{".fig"} or @qcode{".ofig"}, in that order.

@var{copies} is an optional input indicating whether a new figure should
be created (@qcode{"new"}) or whether an existing figure may be reused
(@qcode{"reuse"}).  An existing figure may be reused if the
@qcode{"FileName"} property matches the specified input @var{filename}.
When a figure is reused it becomes the active figure and is shown on top
of other figures.  If the figure was offscreen, it is re-positioned to be
onscreen.  The default value for @var{copies} is @qcode{"new"}.

@var{visibility} is an optional input indicating whether to show the figure
(@qcode{"visible"}) or not (@qcode{"invisible"}).  When @var{visibility} is
specified as an input to @code{openfig} it overrides the visibility setting
stored in @var{filename}.

@xseealso{@ref{XREFopen,,open}, @ref{XREFhgload,,hgload}, @ref{XREFsavefig,,savefig}, @ref{XREFstruct2hdl,,struct2hdl}}
@end deftypefn


@c savefig scripts/plot/util/savefig.m
@anchor{XREFsavefig}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} savefig ()
@deftypefnx {} {} savefig (@var{h})
@deftypefnx {} {} savefig (@var{filename})
@deftypefnx {} {} savefig (@var{h}, @var{filename})
@deftypefnx {} {} savefig (@var{h}, @var{filename}, @qcode{"compact"})
Save figure windows specified by graphics handle(s) @var{h} to file
@var{filename}.

If unspecified, @var{h} is the current figure returned by @code{gcf}.

If unspecified, @var{filename} is set to @file{"Untitled.fig"}.  If
@var{filename} does not have an extension then the default extension
@file{".fig"} will be added.

If the optional third input @qcode{"compact"} is present then the data
will be compressed to save more space.

@xseealso{@ref{XREFhgsave,,hgsave}, @ref{XREFhdl2struct,,hdl2struct}, @ref{XREFopenfig,,openfig}}
@end deftypefn


@node Interacting with Plots
@subsection Interacting with Plots

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

@c ginput scripts/plot/util/ginput.m
@anchor{XREFginput}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{x}, @var{y}, @var{buttons}] =} ginput (@var{n})
@deftypefnx {} {[@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}.

Implementation Note: @code{ginput} is intenteded for 2-D plots.  For 3-D
plots see the @var{currentpoint} property of the current axes which can be
transformed with knowledge of the current @code{view} into data units.
@xseealso{@ref{XREFgtext,,gtext}, @ref{XREFwaitforbuttonpress,,waitforbuttonpress}}
@end deftypefn


@c waitforbuttonpress scripts/gui/waitforbuttonpress.m
@anchor{XREFwaitforbuttonpress}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@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.
@xseealso{@ref{XREFwaitfor,,waitfor}, @ref{XREFginput,,ginput}, @ref{XREFkbhit,,kbhit}}
@end deftypefn


@c gtext scripts/plot/appearance/gtext.m
@anchor{XREFgtext}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} gtext (@var{s})
@deftypefnx {} {} gtext (@{@var{s1}, @var{s2}, @dots{}@})
@deftypefnx {} {} gtext (@{@var{s1}; @var{s2}; @dots{}@})
@deftypefnx {} {} gtext (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@var{h} =} gtext (@dots{})
Place text on the current figure using the mouse.

The string argument @var{s} may be a character array or a cell array
of strings.  If @var{s} has more than one row, each row is used
to create a separate text object after a mouse click.  For example:

Place a single string after one mouse click

@example
gtext ("I clicked here")
@end example

Place two strings after two mouse clicks

@example
gtext (@{"I clicked here"; "and there"@})
@end example

Place two strings, each with two lines, after two mouse clicks

@example
gtext (@{"I clicked", "here"; "and", "there"@})
@end example

Optional @var{property}/@var{value} pairs are passed directly to the
underlying text objects.

The full list of text object properties is documented at
@ref{Text Properties}.

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


More sophisticated user interaction mechanisms can be obtained using the
@nospell{ui*} family of functions, @pxref{UI Elements}.

@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} sombrero ()
@deftypefnx {} {} sombrero (@var{n})
@deftypefnx {} {@var{z} =} sombrero (@dots{})
@deftypefnx {} {[@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})}.

@xseealso{@ref{XREFpeaks,,peaks}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFmesh,,mesh}, @ref{XREFsurf,,surf}}
@end deftypefn


@c peaks scripts/plot/draw/peaks.m
@anchor{XREFpeaks}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} peaks ()
@deftypefnx {} {} peaks (@var{n})
@deftypefnx {} {} peaks (@var{x}, @var{y})
@deftypefnx {} {@var{z} =} peaks (@dots{})
@deftypefnx {} {[@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})}.

@xseealso{@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

The graphics functions use pointers, which are of class graphics_handle, in
order to address the data structures which control visual display.  A
graphics handle may point to any one of a number of different base object
types.  These objects are the graphics data structures themselves.  The
primitive graphic object types are: @code{figure}, @code{axes}, @code{line},
@code{text}, @code{patch}, @code{scatter}, @code{surface}, @code{text},
@code{image}, and @code{light}.

Each of these objects has a function by the same name, and each of these
functions returns a graphics handle pointing to an object of the corresponding
type.

In addition, there are several functions which operate on properties of the
graphics objects and which also return handles.  This includes but is not
limited to the following functions: The functions @code{plot} and @code{plot3}
return a handle pointing to an object of type @code{line}.  The function
@code{subplot} returns a handle pointing to an object of type @code{axes}.
The functions @code{fill}, @code{fill3}, @code{trimesh}, and @code{trisurf}
return a handle pointing to an object of type patch.  The function
@code{scatter3} returns a handle to an object of type scatter.  The functions
@code{slice}, @code{surf}, @code{surfl}, @code{mesh}, @code{meshz},
@code{pcolor}, and @code{waterfall} each return a handle of type surface.  The
function @code{camlight} returns a handle to an object of type light.  The
functions @code{area}, @code{bar}, @code{barh}, @code{contour},
@code{contourf}, @code{contour3}, @code{surfc}, @code{meshc}, @code{errorbar},
@code{quiver}, @code{quiver3}, @code{stair}, @code{stem}, @code{stem3} each
return a handle to a complex data structure as documented in
@ref{Data Sources in Object Groups,,Data Sources}.

The graphics objects are arranged in a hierarchy:

1. The root object is returned by @code{groot} (historically, equivalent to
the handle 0).  In other words, @code{get (groot)} returns the properties of
the root object.

2. Below the root are @code{figure} objects.

3. Below the @code{figure} objects are @code{axes} or @code{hggroup} objects.

4. Below the @code{axes} or @code{hggroup} objects are @code{line},
@code{text}, @code{patch}, @code{scatter}, @code{surface}, @code{image}, and
@code{light} objects.

It is possible to walk this hierarchical tree by querying the @qcode{"parent"}
and @qcode{"children"} properties of the graphics objects.

Graphics handles may be distinguished from function handles
(@pxref{Function Handles}) by means of the function @code{ishghandle}.
@code{ishghandle} returns true if its argument is a handle of a graphics
object.  In addition, a figure or axes object may be tested using
@code{isfigure} or @code{isaxes} respectively.  To test for a specific type of
graphics handle, such as a patch or line object, use @code{isgraphics}.  The
more specific test functions return true only if the argument is both a
graphics handle and of the correct type (figure, axes, specified object type).

The @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 may be obtained in the form of a
structure using @code{s = get (h)}, where @code{h} is the handle of a graphics
object.  If only the names of the properties and the allowed values (for radio
properties only) are wanted, one may use @code{set (h)}.

Thus, for example:

@example
h = figure ();
get (h, "type")
@result{} ans = figure
set (h)
@result{}
        alphamap:
        beingdeleted:  [ @{off@} | on ]
        busyaction:  [ cancel | @{queue@} ]
        buttondownfcn:
        clipping:  [ off | @{on@} ]
        closerequestfcn:
        color:
        colormap:
        createfcn:
        currentaxes:
        deletefcn:
        dockcontrols:  [ @{off@} | on ]
        filename:
        graphicssmoothing:  [ off | @{on@} ]
        handlevisibility:  [ callback | off | @{on@} ]
        ...
@end example

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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{res} =} isprop (@var{obj}, "@var{prop}")
Return true if @var{prop} is a property of the object @var{obj}.

@var{obj} may also be an array of objects in which case @var{res} will be a
logical array indicating whether each handle has the property @var{prop}.

For plotting, @var{obj} is a handle to a graphics object.  Otherwise,
@var{obj} should be an instance of a class.  @code{isprop} reports whether
the class defines a property, but @code{Access} permissions or visibility
restrictions (@code{Hidden = true}) may prevent use by the programmer.
@xseealso{@ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFproperties,,properties}, @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}.

@menu
* Creating Graphics Objects::
* Handle Functions::
@end menu

@table @asis
@c @group

@item root
@cindex root graphics object
@cindex graphics object, root
The top level of the hierarchy and the parent of all figure objects.
Use @code{groot} to obtain the handle of the root graphics object.

@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, surface, or light 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.

@item light
@cindex light graphics object
@cindex graphics object, light
A light object used for lighting effects on patches and surfaces.
@c @end group
@end table

@node Creating Graphics Objects
@subsubsection Creating Graphics Objects
@cindex creating graphics objects

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

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

@c axes scripts/plot/util/axes.m
@anchor{XREFaxes}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} axes ()
@deftypefnx {} {} axes (@var{property}, @var{value}, @dots{})
@deftypefnx {} {} axes (@var{hpar}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} axes (@var{hax})
@deftypefnx {} {@var{h} =} axes (@dots{})
Create a Cartesian 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.  The optional argument @var{hpar} is a graphics handle
specifying the parent for the new axes and may be a figure, uipanel, or
uitab.

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

Programming Note: The full list of properties is documented at
@ref{Axes Properties}.
@xseealso{@ref{XREFgca,,gca}, @ref{XREFset,,set}, @ref{XREFget,,get}}
@end deftypefn


@c line scripts/plot/draw/line.m
@anchor{XREFline}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} line ()
@deftypefnx {} {} line (@var{x}, @var{y})
@deftypefnx {} {} line (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} line ("xdata", @var{x}, "ydata", @var{y})
@deftypefnx {} {} line ("xdata", @var{x}, "ydata", @var{y}, "zdata", @var{z})
@deftypefnx {} {} line (@dots{}, @var{property}, @var{value})
@deftypefnx {} {} line (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} line (@dots{})
Create a line object from @var{x} and @var{y} (and possibly @var{z}) and
insert it in the current axes.

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

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

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

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

If the first argument @var{hax} is an axes handle, then plot into this axes,
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.

Programming Note: The full list of properties is documented at
@ref{Line Properties}.

The function @code{line} differs from @code{plot} in that line objects are
inserted in to the current axes without first clearing the plot.
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} patch ()
@deftypefnx {} {} patch (@var{x}, @var{y}, @var{c})
@deftypefnx {} {} patch (@var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {} {} patch ("Faces", @var{faces}, "Vertices", @var{verts}, @dots{})
@deftypefnx {} {} patch (@dots{}, "@var{prop}", @var{val}, @dots{})
@deftypefnx {} {} patch (@dots{}, @var{propstruct}, @dots{})
@deftypefnx {} {} patch (@var{hax}, @dots{})
@deftypefnx {} {@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{clim} 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{clim} and then
indexing into the current colormap.  More complicated coloring situations
require directly manipulating patch property/value pairs.

Instead of specifying polygons by matrices @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 patch).  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.

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

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

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

Programming Notes:
@enumerate
@item
The full list of properties is documented at @ref{Patch Properties}.
Useful patch properties include: @qcode{"edgecolor"}, @qcode{"facecolor"},
@qcode{"faces"}, @qcode{"vertices"}, and @qcode{"facevertexcdata"}.

@item
Unexpected geometry results can occur from mixing x-y-z and
face-vertex forms of defining geometry.

@item
Unexpected patch color results can occur from using @qcode{"cdata"} color
definitions with face-vertex defined geometry or @qcode{"facevertexcdata"}
color definitions with x-y-z defined geometry.
@end enumerate
@xseealso{@ref{XREFfill,,fill}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c surface scripts/plot/draw/surface.m
@anchor{XREFsurface}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} surface (@var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {} {} surface (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} surface (@var{z}, @var{c})
@deftypefnx {} {} surface (@var{z})
@deftypefnx {} {} surface (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} surface (@var{hax}, @dots{})
@deftypefnx {} {@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:columns (@var{z})} and @var{y} is
@code{1:rows (@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 axes,
rather than the current axes returned by @code{gca}.

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

Programming Note: The full list of properties is documented at
@ref{Surface Properties}.
@xseealso{@ref{XREFsurf,,surf}, @ref{XREFmesh,,mesh}, @ref{XREFpatch,,patch}, @ref{XREFline,,line}}
@end deftypefn


@c light scripts/plot/draw/light.m
@anchor{XREFlight}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} light ()
@deftypefnx {} {} light (@dots{}, "@var{prop}", @var{val}, @dots{})
@deftypefnx {} {} light (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} light (@dots{})
Create a light object in the current axes or for axes @var{hax}.

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

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

Lighting is only supported for OpenGL graphic toolkits (i.e., @qcode{"fltk"}
and @qcode{"qt"}).

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

@table @asis
@item @qcode{"Color":} The color of the light can be passed as an
RGB-vector (e.g., @code{[1 0 0]} for red) or as a string (e.g., @qcode{"r"}
for red).  The default color is white (@code{[1 1 1]}).

@item @qcode{"Position":} The direction from which the light emanates as a
1x3-vector.  The default direction is @code{[1 0 1]}.

@item @qcode{"Style":} This string defines whether the light emanates from a
light source at infinite distance (@qcode{"infinite"}) or from a local point
source (@qcode{"local"}).  The default is @qcode{"infinite"}.
@end table

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

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

Programming Note: The full list of properties is documented at
@ref{Light Properties}.
@xseealso{@ref{XREFlighting,,lighting}, @ref{XREFmaterial,,material}, @ref{XREFpatch,,patch}, @ref{XREFsurface,,surface}}
@end deftypefn


@node Handle Functions
@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{ishghandle}, @code{isgraphics},
@code{isaxes}, and @code{isfigure}.

@c ishghandle libinterp/corefcn/graphics.cc
@anchor{XREFishghandle}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} ishghandle (@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.
@xseealso{@ref{XREFisgraphics,,isgraphics}, @ref{XREFisaxes,,isaxes}, @ref{XREFisfigure,,isfigure}, @ref{XREFishandle,,ishandle}}
@end deftypefn


@c isgraphics scripts/plot/util/isgraphics.m
@anchor{XREFisgraphics}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tf} =} isgraphics (@var{h})
@deftypefnx {} {@var{tf} =} isgraphics (@var{h}, @var{type})
Return true if @var{h} is a graphics handle (of type @var{type}) and false
otherwise.

When no @var{type} is specified the function is equivalent to
@code{ishghandle}.
@xseealso{@ref{XREFishghandle,,ishghandle}, @ref{XREFishandle,,ishandle}, @ref{XREFisaxes,,isaxes}, @ref{XREFisfigure,,isfigure}}
@end deftypefn


@c ishandle scripts/plot/util/ishandle.m
@anchor{XREFishandle}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} ishandle (@var{h})
Return true if @var{h} is a handle to a graphics or Java object 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 handles to graphics
or Java objects and false where they are not.

Programming Note: It is often more useful to test for a specific object
type.  To determine if a handle belongs to a graphics object use
@code{ishghandle} or @code{isgraphics}.  To determine if a handle belongs
to a Java object use @code{isjava}.
@xseealso{@ref{XREFishghandle,,ishghandle}, @ref{XREFisgraphics,,isgraphics}, @ref{XREFisjava,,isjava}}
@end deftypefn


@c isaxes scripts/plot/util/isaxes.m
@anchor{XREFisaxes}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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.
@xseealso{@ref{XREFisfigure,,isfigure}, @ref{XREFishghandle,,ishghandle}, @ref{XREFisgraphics,,isgraphics}}
@end deftypefn


@c isfigure scripts/plot/util/isfigure.m
@anchor{XREFisfigure}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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.
@xseealso{@ref{XREFisaxes,,isaxes}, @ref{XREFishghandle,,ishghandle}, @ref{XREFisgraphics,,isgraphics}}
@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 groot scripts/plot/util/groot.m
@anchor{XREFgroot}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{h} =} groot ()
Return a handle to the root graphics object.

The root graphics object is the ultimate parent of all graphics objects.

In addition, the root object contains information about the graphics
system as a whole such as the @code{ScreenSize}.  Use
@w{@code{get (groot)}}@ to find out what information is available.

Defaults for the graphic system as a whole are specified by setting
properties of the root graphics object that begin with @qcode{"Default"}.
For example, to set the default font for all text objects to FreeSans use

@example
set (groot, "DefaultTextFontName", "FreeSans")
@end example

Default properties can be deleted by using @code{set} with the special
property value of @qcode{"remove"}.  To undo the default font assignment
above use

@example
set (groot, "DefaultTextFontName", "remove")
@end example

Programming Note: The root graphics object is identified by the special
handle value of 0.  At some point this unique value may change, but code can
be made resistant to future changes by using @code{groot} which is
guaranteed to always return the root graphics object.
@xseealso{@ref{XREFgcf,,gcf}, @ref{XREFgca,,gca}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c gcf scripts/plot/util/gcf.m
@anchor{XREFgcf}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@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 (groot, "currentfigure");
@end example

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{h} =} gca ()
Return a handle to the current axes object.

The current axes is the default target for graphics output.  In the case
of a figure with multiple axes, @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 axes 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
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} gco ()
@deftypefnx {} {@var{h} =} gco (@var{hfig})
Return a handle to the current object of the current figure, or a handle
to the current object of the figure with handle @var{hfig}.

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.

@xseealso{@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 (groot)
    @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 graphics object.
As with all functions in Octave, the structure is returned by value, so
modifying it will not modify the internal root 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]}.

Default property values can also be queried if the @code{set} function is
called without a value argument.  When only one argument is given (a graphic
handle) then a structure with defaults for all properties of the given object
type is returned.  For example,

@example
set (gca ())
@end example

@noindent
returns a structure containing the default property values for axes objects.
If @code{set} is called with two arguments (a graphic handle and a property
name) then only the defaults for the requested property are returned.

@c get libinterp/corefcn/graphics.cc
@anchor{XREFget}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} get (@var{h})
@deftypefnx {} {@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.
@xseealso{@ref{XREFset,,set}}
@end deftypefn


@c set libinterp/corefcn/graphics.cc
@anchor{XREFset}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} set (@var{h}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} set (@var{h}, @{@var{properties}@}, @{@var{values}@})
@deftypefnx {} {} set (@var{h}, @var{pv})
@deftypefnx {} {@var{value_list} =} set (@var{h}, @var{property})
@deftypefnx {} {@var{all_value_list} =} set (@var{h})
Set named property values for the graphics handle (or vector of graphics
handles) @var{h}.

There are three ways to give the property names and values:

@itemize
@item as a comma-separated list of @var{property}, @var{value} pairs

Each @var{property} is a string containing the property name, each @var{value}
is a value of the appropriate type for the property.  When there are multiple
handles in @var{h}, each one is assigned the same @var{value}.  For example:

@example
@group
h = plot ([0, 1]);
set (h, 'color', 'green');
@end group
@end example

@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
second case, the first handle in @var{h} will be assigned the values from
the first row of @var{values} and so on.  For example:

@example
@group
h = plot ([0, 1; 1, 0]);
set (h, @{'color'@}, @{'green'; 'red'@});
@end group
@end example

@item as a structure @var{pv}

This is the same as the first case where the field names of @var{pv} represent
the property names, and the field values give the property values.  As with
the first case, it is only possible to set one value for a property which will
be applied to all handles in @var{h}.  For example:

@example
@group
h = plot ([0, 1]);
props.color = 'green';
set (h, props);
@end group
@end example

@end itemize

The three syntaxes for setting properties may appear in any combination.

@code{set} is also used to query the list of values a named property will
take.  @code{@var{clist} = set (@var{h}, "property")} will return the list
of possible values for @qcode{"property"} in the cell list @var{clist}.
If no output variable is used then the list is formatted and printed to the
screen.

If no property is specified (@code{@var{slist} = set (@var{h})}) then a
structure @var{slist} is returned where the fieldnames are the properties of
the object @var{h} and the fields are the list of possible values for each
property.  If no output variable is used then the list is formatted and
printed to the screen.

When querying properties only a single graphics handle @var{h} for a single
graphics object is permitted.

Example Query

@example
@group
hf = figure ();
set (hf, "paperorientation")
@result{}  [ landscape | @{portrait@} ]
@end group
@end example

@noindent
shows the paperorientation property can take two values with the default
being @qcode{"portrait"}.
@xseealso{@ref{XREFget,,get}}
@end deftypefn


@c ancestor scripts/plot/util/ancestor.m
@anchor{XREFancestor}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{parent} =} ancestor (@var{h}, @var{type})
@deftypefnx {} {@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.
@xseealso{@ref{XREFfindobj,,findobj}, @ref{XREFfindall,,findall}, @ref{XREFallchild,,allchild}}
@end deftypefn


@c allchild scripts/plot/util/allchild.m
@anchor{XREFallchild}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@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.
@xseealso{@ref{XREFfindall,,findall}, @ref{XREFfindobj,,findobj}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c findfigs scripts/plot/util/findfigs.m
@anchor{XREFfindfigs}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} findfigs ()
Find all visible figures that are currently off the screen and move them
onto the screen.
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@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"}.
@xseealso{@ref{XREFstruct2hdl,,struct2hdl}, @ref{XREFhgsave,,hgsave}, @ref{XREFfindobj,,findobj}}
@end deftypefn


@c struct2hdl scripts/plot/util/struct2hdl.m
@anchor{XREFstruct2hdl}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} struct2hdl (@var{s})
@deftypefnx {} {@var{h} =} struct2hdl (@var{s}, @var{p})
@deftypefnx {} {@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 object.

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.
@xseealso{@ref{XREFhdl2struct,,hdl2struct}, @ref{XREFhgload,,hgload}, @ref{XREFfindobj,,findobj}}
@end deftypefn


@c copyobj scripts/plot/util/copyobj.m
@anchor{XREFcopyobj}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hnew} =} copyobj (@var{horig})
@deftypefnx {} {@var{hnew} =} copyobj (@var{horig}, @var{hparent})
Construct a copy of the graphic objects associated with the handles
@var{horig} and return new handles @var{hnew} to the new objects.

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

If @var{horig} is a vector of handles, and @var{hparent} is a scalar,
then each handle in the vector @var{hnew} has its @qcode{"Parent"} property
set to @var{hparent}.  Conversely, if @var{horig} is a scalar and
@var{hparent} a vector, then each parent object will receive a copy of
@var{horig}.  If @var{horig} and @var{hparent} are both vectors with the
same number of elements then @code{@var{hnew}(i)} will have parent
@code{@var{hparent}(i)}.
@xseealso{@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 Properties::
* Figure Properties::
* Axes Properties::
* Legend Properties::
* Line Properties::
* Text Properties::
* Image Properties::
* Patch Properties::
* Scatter Properties::
* Surface Properties::
* Light Properties::
* Uimenu Properties::
* Uibuttongroup Properties::
* Uicontextmenu Properties::
* Uipanel Properties::
* Uicontrol Properties::
* Uitable Properties::
* Uitoolbar Properties::
* Uipushtool Properties::
* Uitoggletool Properties::
@end menu

In this section the graphics object properties are discussed in detail,
starting with the root properties and continuing through the object hierarchy.
The documentation about a specific graphics object can be displayed using
@code{doc} function, e.g., @code{doc ("axes properties")} will show
@ref{Axes Properties}.

The allowed values for radio (string) properties can be retrieved
programmatically or displayed using the one or two argument calling form of the
@code{set} function.  @xref{XREFset, , set}.

Any properties marked as either unused or unimplemented in the following
documentation are accepted without error by Octave.  Values for those properties
are stored in the object but have no effect on the object.

Default property values are enclosed in @{ @}.

@node Root Properties
@subsubsection Root Properties
@prindex @sortas{@ Root Properties} Root Properties

@include plot-rootproperties.texi


@node Figure Properties
@subsubsection Figure Properties
@prindex @sortas{@ Figure Properties} Figure Properties

@include plot-figureproperties.texi


@node Axes Properties
@subsubsection Axes Properties
@prindex @sortas{@ Axes Properties} Axes Properties

@include plot-axesproperties.texi


@node Legend Properties
@subsubsection Legend Properties
@prindex @sortas{@ Legend Properties} Legend Properties

@include plot-legendproperties.texi


@node Line Properties
@subsubsection Line Properties
@prindex @sortas{@ Line Properties} Line Properties

@include plot-lineproperties.texi


@node Text Properties
@subsubsection Text Properties
@prindex @sortas{@ Text Properties} Text Properties

@include plot-textproperties.texi


@node Image Properties
@subsubsection Image Properties
@prindex @sortas{@ Image Properties} Image Properties

@include plot-imageproperties.texi


@node Patch Properties
@subsubsection Patch Properties
@prindex @sortas{@ Patch Properties} Patch Properties

@include plot-patchproperties.texi


@node Scatter Properties
@subsubsection Scatter Properties
@prindex @sortas{@ Scatter Properties} Scatter Properties

@include plot-scatterproperties.texi


@node Surface Properties
@subsubsection Surface Properties
@prindex @sortas{@ Surface Properties} Surface Properties

@include plot-surfaceproperties.texi


@node Light Properties
@subsubsection Light Properties
@prindex @sortas{@ Light Properties} Light Properties

@include plot-lightproperties.texi


@node Uimenu Properties
@subsubsection Uimenu Properties
@prindex @sortas{@ Uimenu Properties} Uimenu Properties

@include plot-uimenuproperties.texi


@node Uibuttongroup Properties
@subsubsection Uibuttongroup Properties
@prindex @sortas{@ Uibuttongroup Properties} Uibuttongroup Properties

@include plot-uibuttongroupproperties.texi


@node Uicontextmenu Properties
@subsubsection Uicontextmenu Properties
@prindex @sortas{@ Uicontextmenu Properties} Uicontextmenu Properties

@include plot-uicontextmenuproperties.texi


@node Uipanel Properties
@subsubsection Uipanel Properties
@prindex @sortas{@ Uipanel Properties} Uipanel Properties

@include plot-uipanelproperties.texi


@node Uicontrol Properties
@subsubsection Uicontrol Properties
@prindex @sortas{@ Uicontrol Properties} Uicontrol Properties

@include plot-uicontrolproperties.texi


@node Uitable Properties
@subsubsection Uitable Properties
@cindex uitable properties

@include plot-uitableproperties.texi


@node Uitoolbar Properties
@subsubsection Uitoolbar Properties
@prindex @sortas{@ Uitoolbar Properties} Uitoolbar Properties

@include plot-uitoolbarproperties.texi


@node Uipushtool Properties
@subsubsection Uipushtool Properties
@prindex @sortas{@ Uipushtool Properties} Uipushtool Properties

@include plot-uipushtoolproperties.texi


@node Uitoggletool Properties
@subsubsection Uitoggletool Properties
@prindex @sortas{@ Uitoggletool Properties} Uitoggletool Properties

@include plot-uitoggletoolproperties.texi


@node Searching Properties
@subsection Searching Properties

@c findobj scripts/plot/util/findobj.m
@anchor{XREFfindobj}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} findobj ()
@deftypefnx {} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, @dots{})
@deftypefnx {} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @var{prop_name}, @var{prop_value})
@deftypefnx {} {@var{h} =} findobj ("-property", @var{prop_name})
@deftypefnx {} {@var{h} =} findobj ("-regexp", @var{prop_name}, @var{pattern})
@deftypefnx {} {@var{h} =} findobj (@var{hlist}, @dots{})
@deftypefnx {} {@var{h} =} findobj (@var{hlist}, "flat", @dots{})
@deftypefnx {} {@var{h} =} findobj (@var{hlist}, "-depth", @var{d}, @dots{})
Find graphics objects with specified properties.

When called without arguments, return all graphic objects beginning with the
root object (0) and including all of its descendants.

The simplest form for narrowing the results is

@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 (equivalent to @code{-and}) are returned.

The search can be limited to a particular set of objects and their
descendants, by passing a handle or set of handles @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 through 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 of 0 is also equivalent to the
@qcode{"flat"} argument.  The default depth value is @code{Inf} which
includes all descendants.

A specified logical operator may be used between @var{prop_name},
@var{prop_value} pairs.  The supported logical operators are:
@qcode{"-and"}, @qcode{"-or"}, @qcode{"-xor"}, @qcode{"-not"}.  Example code
to locate all figure and axes objects is

@example
findobj ("type", "figure", "-or", "type", "axes")
@end example

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 which have a property name can be found with the
@qcode{"-property"} option.  For example, code to locate objects with a
@qcode{"meshstyle"} property is

@example
findobj ("-property", "meshstyle")
@end example

Implementation Note: The search only includes objects with visible
handles (@w{HandleVisibility} = @qcode{"on"}).
@xref{XREFfindall,,@code{findall}}, to search for all objects including
hidden ones.
@xseealso{@ref{XREFfindall,,findall}, @ref{XREFallchild,,allchild}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


@c findall scripts/plot/util/findall.m
@anchor{XREFfindall}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} findall ()
@deftypefnx {} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, @dots{})
@deftypefnx {} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @var{prop_name}, @var{prop_value})
@deftypefnx {} {@var{h} =} findall ("-property", @var{prop_name})
@deftypefnx {} {@var{h} =} findall ("-regexp", @var{prop_name}, @var{pattern})
@deftypefnx {} {@var{h} =} findall (@var{hlist}, @dots{})
@deftypefnx {} {@var{h} =} findall (@var{hlist}, "flat", @dots{})
@deftypefnx {} {@var{h} =} findall (@var{hlist}, "-depth", @var{d}, @dots{})
Find graphics object, including hidden ones, with specified properties.

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,,@code{findobj}}.
@xseealso{@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 (groot, "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 object so the default property value will apply
to all line objects.  However, default values are hierarchical, so defaults set
in a figure objects override those set in the root object.  Likewise, defaults
set in an axes object override those set in figure or root objects.  For
example,

@example
@group
subplot (2, 1, 1);
set (groot, "defaultlinecolor", "red");
set (1, "defaultlinecolor", "green");
set (gca (), "defaultlinecolor", "blue");
line (1:10, rand (1, 10));
subplot (2, 1, 2);
line (1:10, rand (1, 10));
figure (2)
line (1:10, rand (1, 10));
@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 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.

By default, high level plotting functions such as @code{plot} reset and
redefine axes properties independently from the defaults.  An example of such
property is the axes @code{box} property: it is set @code{on} by high level 2-D
graphics functions regardless of the property @qcode{"defaultaxesbox"}.  Use
the @code{hold} function to prevent this behavior:

@example
@group
set (groot, "defaultaxesbox", "off");
subplot (2, 1, 1);
plot (1:10)
title ("Box is on anyway")
subplot (2, 1, 2);
hold on
plot (1:10)
title ("Box is off")
@end group
@end example

@c reset libinterp/corefcn/graphics.cc
@anchor{XREFreset}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} reset (@var{h})
Reset the properties of the graphic object @var{h} to their default values.

For figures, the properties @qcode{"position"}, @qcode{"units"},
@qcode{"windowstyle"}, and @qcode{"paperunits"} are not affected.
For axes, the properties @qcode{"position"} and @qcode{"units"} are
not affected.

The input @var{h} may also be a vector of graphic handles in which case
each individual object will be reset.
@xseealso{@ref{XREFcla,,cla}, @ref{XREFclf,,clf}, @ref{XREFnewplot,,newplot}}
@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 object.  The command

@example
get (groot, "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::
* Transform Groups::
* Graphics Toolkits::
@end menu


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

Colors may be specified in three ways: 1) RGB triplets, 2) by name, or 3) by
HTML notation.

@table @asis

@item RGB triplet

An RGB triplet is a 1x3 vector where each value is between 0 and 1 inclusive.
The first value represents the percentage of Red, the second value the
percentage of Green, and the third value the percentage of Blue.  For example,
@code{[1, 0, 1]} represents full Red and Blue channels resulting in the color
magenta.

@item short or long name

Eight colors can be specified directly by name or by a single character short
name.

@multitable @columnfractions 0.21 0.79
@headitem Name @tab Color
@item @samp{k}, @qcode{"black"}   @tab blacK
@item @samp{r}, @qcode{"red"}     @tab Red
@item @samp{g}, @qcode{"green"}   @tab Green
@item @samp{b}, @qcode{"blue"}    @tab Blue
@item @samp{y}, @qcode{"yellow"}  @tab Yellow
@item @samp{m}, @qcode{"magenta"} @tab Magenta
@item @samp{c}, @qcode{"cyan"}    @tab Cyan
@item @samp{w}, @qcode{"white"}   @tab White
@end multitable

@item HTML notation

HTML notation is a string that begins with the character @samp{#} and is
followed by either 3 or 6 hexadecimal digits.  As with RGB triplets, each
hexadecimal number represents the fraction of the Red, Green, and Blue channels
present in the specified color.  For example, @qcode{"#FF00FF"} represents
the color magenta.

@end table

@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 @asis
@item @qcode{"-"}
Solid line.  [default]

@item @qcode{"--"}
Dashed line.

@item @qcode{":"}
Dotted line.

@item @qcode{"-."}
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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{style}, @var{color}, @var{marker}, @var{msg}] =} colstyle (@var{style})
Parse the line specification @var{style} 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 (hsrc, evt)
  @dots{}
endfunction
@end group
@end example

@noindent
where @code{hsrc} is a handle to the source of the callback, and @code{evt}
gives some event specific data.

The function can be provided as a function handle to a plain Octave function,
as an anonymous function, or as a string representing an Octave command.  The
latter syntax is not recommended since syntax errors will only occur when the
string is evaluated.
@xref{Function Handles and Anonymous Functions, , Function Handles section}.

This can then be associated with an object either at the object's creation, or
later with the @code{set} function.  For example,

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

@noindent
where at the moment that the plot is deleted, the message
@qcode{"Window Deleted"} will be displayed.

Additional user arguments can be passed to callback functions, and will be
passed after the two default arguments.  For example:

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

@strong{Caution:} The second argument in callback functions---@code{evt}---is
only partially implemented in the Qt graphics toolkit:

@itemize @bullet
@item Mouse click events:
@code{evt} is a class @code{double} value: 1 for left, 2 for middle, and 3 for
right click.

@item Key press events:
@code{evt} is a structure with fields @code{Key} (string), @code{Character}
(string), and @code{Modifier} (cell array of strings).

@item Other events:
@code{evt} is a class @code{double} empty matrix.
@end itemize

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

@itemize @bullet
@item CreateFcn:
called at the moment of the objects creation.  It is not called if the
object is altered in any way, and so it only makes sense to define this
callback in the function call that defines the object.  Callbacks that
are added to @code{CreateFcn} later with the @code{set} function will
never be executed.

@item DeleteFcn:
called at the moment an object is deleted.

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

By default callback functions are queued (they are executed one after the other
in the event queue) unless the @code{drawnow}, @code{figure}, @code{waitfor},
@code{getframe}, or @code{pause} functions are used.  If an executing callback
invokes one of those functions, it causes Octave to flush the event queue,
which results in the executing callback being interrupted.

It is possible to specify that an object's callbacks should not be interrupted
by setting the object's @code{interruptible} property to @qcode{"off"}.  In
this case, Octave decides what to do based on the @code{busyaction} property of
the @strong{interrupting} callback object:

@table @asis
@item @code{queue} (the default)
The interrupting callback is executed after the executing callback has
returned.

@item @code{cancel}
The interrupting callback is discarded.
@end table

The @code{interruptible} property has no effect when the interrupting callback
is a @code{deletefcn}, or a figure @code{resizefcn} or @code{closerequestfcn}.
Those callbacks always interrupt the executing callback.

The handle to the object that holds the callback being executed can be
obtained with the @code{gcbo} function.  The handle to the ancestor figure
of this object may be obtained using the @code{gcbf} function.

@c gcbo scripts/plot/util/gcbo.m
@anchor{XREFgcbo}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} gcbo ()
@deftypefnx {} {[@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.

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@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}.

@xseealso{@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/gui/setappdata.m
@anchor{XREFsetappdata}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} setappdata (@var{h}, @var{name}, @var{value})
@deftypefnx {} {} setappdata (@var{h}, @var{name1}, @var{value1}, @var{name2}, @var{value2}, @dots{})
@deftypefnx {} {} setappdata (@var{h}, @{@var{name1}, @var{name2}, @dots{}@}, @{@var{value1}, @var{value2}, @dots{}@})
Set the application data @var{name} to @var{value} for the graphics object
with handle @var{h}.

@var{h} may also be a vector of graphics handles.  If the application data
with the specified @var{name} does not exist, it is created.

Multiple @var{name}/@var{value} pairs can be specified.  Alternatively, a
cell array of @var{names} and a corresponding cell array of @var{values} can
be specified.  For details on obtaining a list of valid application data
properties, @pxref{XREFgetappdata,,@code{getappdata}}.

@xseealso{@ref{XREFgetappdata,,getappdata}, @ref{XREFisappdata,,isappdata}, @ref{XREFrmappdata,,rmappdata}, @ref{XREFguidata,,guidata}, @ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFgetpref,,getpref}, @ref{XREFsetpref,,setpref}}
@end deftypefn


@c getappdata scripts/gui/getappdata.m
@anchor{XREFgetappdata}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{value} =} getappdata (@var{h}, @var{name})
@deftypefnx {} {@var{appdata} =} getappdata (@var{h})
Return the @var{value} of the application data @var{name} for the graphics
object with handle @var{h}.

@var{h} may also be a vector of graphics handles.  If no second argument
@var{name} is given then @code{getappdata} returns a structure,
@var{appdata}, whose fields correspond to the appdata properties.

@xseealso{@ref{XREFsetappdata,,setappdata}, @ref{XREFisappdata,,isappdata}, @ref{XREFrmappdata,,rmappdata}, @ref{XREFguidata,,guidata}, @ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFgetpref,,getpref}, @ref{XREFsetpref,,setpref}}
@end deftypefn


@c rmappdata scripts/gui/rmappdata.m
@anchor{XREFrmappdata}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} rmappdata (@var{h}, @var{name})
@deftypefnx {} {} rmappdata (@var{h}, @var{name1}, @var{name2}, @dots{})
Delete the application data @var{name} from the graphics object with handle
@var{h}.

@var{h} may also be a vector of graphics handles.  Multiple application data
names may be supplied to delete several properties at once.

@xseealso{@ref{XREFsetappdata,,setappdata}, @ref{XREFgetappdata,,getappdata}, @ref{XREFisappdata,,isappdata}}
@end deftypefn


@c isappdata scripts/gui/isappdata.m
@anchor{XREFisappdata}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{valid} =} isappdata (@var{h}, @var{name})
Return true if the named application data, @var{name}, exists for the
graphics object with handle @var{h}.

@var{h} may also be a vector of graphics handles.
@xseealso{@ref{XREFgetappdata,,getappdata}, @ref{XREFsetappdata,,setappdata}, @ref{XREFrmappdata,,rmappdata}, @ref{XREFguidata,,guidata}, @ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFgetpref,,getpref}, @ref{XREFsetpref,,setpref}}
@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} hggroup ()
@deftypefnx {} {} hggroup (@var{hax})
@deftypefnx {} {} hggroup (@dots{}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {@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 full list of properties is documented at
@ref{Axes Properties}.

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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} addproperty (@var{name}, @var{h}, @var{type})
@deftypefnx {} {} 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 one 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

@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


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

@xseealso{@ref{XREFdellistener,,dellistener}, @ref{XREFaddproperty,,addproperty}, @ref{XREFhggroup,,hggroup}}
@end deftypefn


@c dellistener libinterp/corefcn/graphics.cc
@anchor{XREFdellistener}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


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

@xseealso{@ref{XREFaddlistener,,addlistener}}
@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hlink} =} linkprop (@var{h}, "@var{prop}")
@deftypefnx {} {@var{hlink} =} linkprop (@var{h}, @{"@var{prop1}", "@var{prop2}", @dots{}@})
Link graphic object properties, such that a change in one is propagated to
the others.

The input @var{h} is a vector of graphic handles to link.

@var{prop} may be a string when linking a single property, or a cell array
of strings for multiple properties.  During the linking process all
properties in @var{prop} will initially be set to the values that exist on
the first object in the list @var{h}.

The function returns @var{hlink} which is a special object describing the
link.  As long as the reference @var{hlink} exists, the link between graphic
objects will be active.  This means that @var{hlink} must be preserved in
a workspace variable, a global variable, or otherwise stored using a
function such as @code{setappdata} or @code{guidata}.  To unlink properties,
execute @code{clear @var{hlink}}.

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

@xseealso{@ref{XREFlinkaxes,,linkaxes}, @ref{XREFaddlistener,,addlistener}}
@end deftypefn


@c linkaxes scripts/plot/util/linkaxes.m
@anchor{XREFlinkaxes}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} linkaxes (@var{hax})
@deftypefnx {} {} linkaxes (@var{hax}, @var{optstr})
Link the axis limits of 2-D plots such that a change in one is propagated
to the others.

The axes handles to be linked are passed as the first argument @var{hax}.

The optional second argument is a string which defines which axis limits
will be linked.  The possible values for @var{optstr} are:

@table @asis
@item @qcode{"x"}
Link x-axes

@item @qcode{"y"}
Link y-axes

@item @qcode{"xy"} (default)
Link both axes

@item @qcode{"off"}
Turn off linking
@end table

If unspecified the default is to link both X and Y axes.

When linking, the limits from the first axes in @var{hax} are applied to the
other axes in the list.  Subsequent changes to any one of the axes will be
propagated to the others.

@xseealso{@ref{XREFlinkprop,,linkprop}, @ref{XREFaddproperty,,addproperty}}
@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::
* Stair Group::
* Stem Series::
* Surface Group::
@end menu

@node Data Sources in Object Groups
@subsubsection Data Sources in Object Groups
@cindex data sources in object groups

All of the group objects contain data source parameters.  There are
string parameters that contain an expression that is evaluated to update
the relevant data property of the group when the @code{refreshdata}
function is called.

@c refreshdata scripts/plot/util/refreshdata.m
@anchor{XREFrefreshdata}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} refreshdata ()
@deftypefnx {} {} refreshdata (@var{h})
@deftypefnx {} {} 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 FIXME: Add the description of the linkdata function here when it is written.
@c Remove the explicit anchor when you add the corresponding @DOCSTRING 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.  They are also 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, @nospell{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 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 Transform Groups
@subsection Transform Groups
@cindex transform groups

@c FIXME: Need to add documentation on transforms.

@c hgtransform scripts/plot/util/hgtransform.m
@anchor{XREFhgtransform}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} hgtransform ()
@deftypefnx {} {@var{h} =} hgtransform (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{h} =} hgtransform (@var{hax}, @dots{})

Create a graphics transform object.

FIXME: Need to write documentation.
FIXME: Add <makehgtform> to seealso list when it is implemented.
@xseealso{@ref{XREFhggroup,,hggroup}}
@end deftypefn


@c @DOCSTRING(makehgtform)

@node Graphics Toolkits
@subsection Graphics Toolkits
@cindex graphics toolkits
@cindex toolkits, graphics

@c graphics_toolkit scripts/plot/util/graphics_toolkit.m
@anchor{XREFgraphics_toolkit}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tkit} =} graphics_toolkit ()
@deftypefnx {} {@var{tkit} =} graphics_toolkit (@var{hlist})
@deftypefnx {} {} graphics_toolkit (@var{name})
@deftypefnx {} {} 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.

@xseealso{@ref{XREFavailable_graphics_toolkits,,available_graphics_toolkits}}
@end deftypefn


@c available_graphics_toolkits libinterp/corefcn/graphics.cc
@anchor{XREFavailable_graphics_toolkits}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{toolkits} =} available_graphics_toolkits ()
Return a cell array of registered graphics toolkits.
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{toolkits} =} loaded_graphics_toolkits ()
Return a cell array of the currently loaded graphics toolkits.
@xseealso{@ref{XREFavailable_graphics_toolkits,,available_graphics_toolkits}}
@end deftypefn


@c register_graphics_toolkit libinterp/corefcn/graphics.cc
@anchor{XREFregister_graphics_toolkit}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} register_graphics_toolkit ("@var{toolkit}")
List @var{toolkit} as an available graphics toolkit.

Programming Note: No input validation is done on the input string; it is simply
added to the list of possible graphics toolkits.
@xseealso{@ref{XREFavailable_graphics_toolkits,,available_graphics_toolkits}}
@end deftypefn


@menu
* Customizing Toolkit Behavior::
* Hardware vs Software Rendering::
* Precision issues::
@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.in.m
@anchor{XREFgnuplot_binary}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{prog}, @var{args}] =} gnuplot_binary ()
@deftypefnx {} {[@var{old_prog}, @var{old_args}] =} gnuplot_binary (@var{new_prog})
@deftypefnx {} {[@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 @qcode{"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}.
@xseealso{@ref{XREFgraphics_toolkit,,graphics_toolkit}}
@end deftypefn


@cindex GNUTERM

In addition, the gnuplot program usually provides a number of different
interfaces, known as terminals.  Octave normally chooses a default terminal,
but you can override this with the environment variable @env{GNUTERM}.  This
variable may be set in the shell before starting Octave or from within Octave
before plotting for the first time.  For example:

@example
@group
setenv ("GNUTERM", "wxt")
graphics_toolkit ("gnuplot")
plot (1:10)
@end group
@end example

@node Hardware vs Software Rendering
@subsubsection Hardware vs Software Rendering
@cindex opengl rendering slow windows

When using the Windows installer for Octave, the user has the option to select
between "System OpenGL" and "Software OpenGL" renderers.  The choice between
hardware or software rendering affects the OpenGL graphics toolkits
(@qcode{"qt"} and @qcode{"fltk"}) only.  Software rendering can be used to
avoid rendering and printing issues due to imperfect OpenGL driver
implementations for diverse graphic cards from different vendors (notably
integrated Intel graphics).  The downside is that software rendering may be
considerably slower than hardware-accelerated rendering (and it might not work
correctly on 32-bit platforms or @nospell{WoW64}).  To permanently switch
between hardware-accelerated rendering with your graphics card drivers and
software rendering, use the "OpenGL Switcher" application from the Start menu
while Octave is closed.  Alternatively, rename the following file while Octave
is closed:

@file{@var{octave-home}\bin\opengl32.dll}
@*where @var{octave-home} is the directory returned by
@ref{XREFOCTAVE_HOME, , @w{@code{OCTAVE_HOME}}}, i.e., the directory in which
Octave is installed (the default is
@file{C:\Program Files\GNU Octave\Octave\Octave-@var{version}\mingw64}).
Change the file extension to @file{.bak} for hardware rendering or to
@file{.dll} for software rendering.

@node Precision issues
@subsubsection Precision issues
@cindex opengl single precision date time

The OpenGL graphics toolkits (@qcode{"qt"} and @qcode{"fltk"}) use single
precision for rendering.  This limitation in particular applies to plots of
time series against serial dates as used by the @code{datenum}, @code{datestr},
@code{datestruct}, and @code{datetick} functions.

Serial dates encode timestamps as days elapsed since the year zero with hours,
minutes, seconds as the fractional part.  On December 31st 1999, the serial
date representation was 730485.  A double precision variable with this integer
part allows for a resolution in its fractional part of 1.2e-10, representing
about 5 microseconds.  But with single precision, the resolution is reduced to
about 0.06, representing 45 minutes.  Any attempt to plot timestamped data
with finer granularity will result in a distorted graph.

As a workaround, it is possible to use the @qcode{"gnuplot"} graphics toolkit
or subtract 2000 years---i.e., @code{datenum (2000, 0, 0)} or 730485---from the
time values.  Due to the fact that the calendar structure repeats every 2000
years, the relation between year, month, day of month and day of week will stay
unchanged and the ticks and ticklabels produced by the @code{datetick} function
will still be correct.  Only years will lack the millennium digit.  Thus,
"2020" will be printed as "20".  For example:

@example
@group
# timestamps of 24 hours in one minute steps
t = datenum (2020, 1, 1):(1/1440):datenum (2020, 1, 2);

# some example time series data
x = -cos (2*pi*t) + rand (size (t)) / 10;

subplot (1, 2, 1);
plot (t, x);
datetick ("x");
xlabel ("serial date");
title ("problem");

subplot (1, 2, 2);
plot (t - 730485, x);
datetick ("x");
xlabel ("2000 years off");
title ("workaround");
@end group
@end example

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

@float Figure,fig:precisiondate
@center @image{precisiondate,4in}
@caption{Single precision issues with OpenGL graphics toolkits}
@end float
@end ifnotinfo

Similarly, other data can be translated or re-scaled to work around this issue.