@c Copyright (C) 1996-2022 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

@DOCSTRING(plot)

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

@DOCSTRING(plotyy)

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.

@DOCSTRING(semilogx)

@DOCSTRING(semilogy)

@DOCSTRING(loglog)

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

@DOCSTRING(bar)

@DOCSTRING(barh)

@DOCSTRING(hist)

@DOCSTRING(stemleaf)

@DOCSTRING(printd)

@DOCSTRING(stairs)

@DOCSTRING(stem)

@DOCSTRING(stem3)

@DOCSTRING(scatter)

@DOCSTRING(plotmatrix)

@DOCSTRING(pareto)

@DOCSTRING(rose)

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

@DOCSTRING(contour)

@DOCSTRING(contourf)

@DOCSTRING(contourc)

@DOCSTRING(contour3)

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

@DOCSTRING(errorbar)

@DOCSTRING(semilogxerr)

@DOCSTRING(semilogyerr)

@DOCSTRING(loglogerr)

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

@DOCSTRING(polar)

@DOCSTRING(pie)

@DOCSTRING(pie3)

@DOCSTRING(quiver)

@DOCSTRING(quiver3)

@DOCSTRING(streamribbon)

@DOCSTRING(streamtube)

@DOCSTRING(ostreamtube)

@DOCSTRING(streamline)

@DOCSTRING(stream2)

@DOCSTRING(stream3)

@DOCSTRING(compass)

@DOCSTRING(feather)

@DOCSTRING(pcolor)

@DOCSTRING(area)

@DOCSTRING(fill)

@DOCSTRING(fill3)

@DOCSTRING(comet)

@DOCSTRING(comet3)

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

@DOCSTRING(axis)

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

@DOCSTRING(caxis)

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

@c Add cross-references and function index entries for other limit functions.
@anchor{XREFylim}
@anchor{XREFzlim}
@findex ylim
@findex zlim
@DOCSTRING(xlim)

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.
@anchor{XREFyticks}
@anchor{XREFzticks}
@anchor{XREFrticks}
@anchor{XREFthetaticks}
@findex yticks
@findex zticks
@findex rticks
@findex thetaticks
@DOCSTRING(xticks)

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 change the
@c        associated axis properties.
@c        Matlab also implements rticklabels and thetaticklabels.
@anchor{XREFyticklabels}
@anchor{XREFzticklabels}
@findex yticklabels
@findex zticklabels
@DOCSTRING(xticklabels)

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.

@anchor{XREFytickangle}
@anchor{XREFztickangle}
@findex ytickangle
@findex ztickangle
@DOCSTRING(xtickangle)

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

@DOCSTRING(fplot)

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

@DOCSTRING(ezplot)

@DOCSTRING(ezcontour)

@DOCSTRING(ezcontourf)

@DOCSTRING(ezpolar)

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

@DOCSTRING(rectangle)

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

@DOCSTRING(mesh)

@DOCSTRING(meshc)

@DOCSTRING(meshz)

@DOCSTRING(hidden)

@DOCSTRING(surf)

@DOCSTRING(surfc)

@DOCSTRING(surfl)

@DOCSTRING(surfnorm)

@DOCSTRING(isosurface)

@DOCSTRING(isonormals)

@DOCSTRING(isocaps)

@DOCSTRING(isocolors)

@DOCSTRING(smooth3)

@DOCSTRING(reducevolume)

@DOCSTRING(reducepatch)

@DOCSTRING(shrinkfaces)

@DOCSTRING(diffuse)

@DOCSTRING(specular)

@DOCSTRING(lighting)

@DOCSTRING(material)

@DOCSTRING(camlight)

@DOCSTRING(lightangle)

@DOCSTRING(meshgrid)

@DOCSTRING(ndgrid)

@DOCSTRING(plot3)

@DOCSTRING(view)

@DOCSTRING(camlookat)

@DOCSTRING(campos)

@DOCSTRING(camorbit)

@DOCSTRING(camroll)

@DOCSTRING(camtarget)

@DOCSTRING(camup)

@DOCSTRING(camva)

@DOCSTRING(camzoom)

@DOCSTRING(slice)

@DOCSTRING(ribbon)

@DOCSTRING(shading)

@DOCSTRING(scatter3)

@DOCSTRING(waterfall)

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

@DOCSTRING(daspect)

@DOCSTRING(pbaspect)

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

@DOCSTRING(ezplot3)

@DOCSTRING(ezmesh)

@DOCSTRING(ezmeshc)

@DOCSTRING(ezsurf)

@DOCSTRING(ezsurfc)

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

@DOCSTRING(cylinder)

@DOCSTRING(sphere)

@DOCSTRING(ellipsoid)

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

@DOCSTRING(title)

@DOCSTRING(legend)

@DOCSTRING(text)

@c Add cross-references and function index entries for other label functions.
@anchor{XREFylabel}
@anchor{XREFzlabel}
@findex ylabel
@findex zlabel
@DOCSTRING(xlabel)

@DOCSTRING(clabel)

@DOCSTRING(box)

@DOCSTRING(grid)

@DOCSTRING(colorbar)

@DOCSTRING(annotation)

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

@DOCSTRING(subplot)

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

@DOCSTRING(figure)

@node Manipulation of Plot Objects
@subsection Manipulation of Plot Objects
@cindex plotting, object manipulation

@DOCSTRING(pan)

@DOCSTRING(rotate)

@DOCSTRING(rotate3d)

@DOCSTRING(zoom)

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

@DOCSTRING(drawnow)

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.

@DOCSTRING(refresh)

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.

@DOCSTRING(newplot)

@DOCSTRING(hold)

@DOCSTRING(ishold)
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.

@DOCSTRING(clf)

@DOCSTRING(cla)

@DOCSTRING(shg)

@DOCSTRING(delete)

@DOCSTRING(close)

@DOCSTRING(closereq)

@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 you printer and
to save plots in a variety of formats.  For example,

@example
print -dpsc
@end example

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

@example
print -deps foo.eps
@end example

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

The current graphic toolkits produce very similar graphic displays, but differ
in their capability to display unusual text and in their ability to print
such text.  In general, the @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.  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

@DOCSTRING(print)

@DOCSTRING(saveas)

@DOCSTRING(orient)

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

@DOCSTRING(hgsave)

@DOCSTRING(hgload)

@DOCSTRING(openfig)

@DOCSTRING(savefig)

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

@DOCSTRING(ginput)

@DOCSTRING(waitforbuttonpress)

@DOCSTRING(gtext)

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.

@DOCSTRING(sombrero)

@DOCSTRING(peaks)
@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}.

@DOCSTRING(isprop)

@node Graphics Objects
@subsection Graphics Objects
@cindex graphics objects

The hierarchy of graphics objects was explained above.
@xref{Introduction to Graphics Structures}.  Here the
specific objects are described, and the properties contained in
these objects are discussed.  Keep in mind that
graphics objects are always referenced by @dfn{handle}.

@table @asis
@c @group

@item root
@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

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

@DOCSTRING(axes)

@DOCSTRING(line)

@DOCSTRING(patch)

@DOCSTRING(surface)

@DOCSTRING(light)

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

@DOCSTRING(ishghandle)

@DOCSTRING(isgraphics)

@DOCSTRING(ishandle)

@DOCSTRING(isaxes)

@DOCSTRING(isfigure)

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.

@DOCSTRING(groot)

@DOCSTRING(gcf)

@DOCSTRING(gca)

@DOCSTRING(gco)

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.

@DOCSTRING(get)

@DOCSTRING(set)

@DOCSTRING(ancestor)

@DOCSTRING(allchild)

@DOCSTRING(findfigs)

@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

@DOCSTRING(hdl2struct)

@DOCSTRING(struct2hdl)

@DOCSTRING(copyobj)

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

In the following documentation default 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

@DOCSTRING(findobj)

@DOCSTRING(findall)
@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

@DOCSTRING(reset)

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]

@c Special handling required to avoid '--' becoming single en-dash in Info
@ifnottex

@item @verb{|"--"|}
@end ifnottex
@iftex

@item @code{"--"}
@end iftex
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.

@DOCSTRING(colstyle)

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

@DOCSTRING(gcbo)

@DOCSTRING(gcbf)

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.

@DOCSTRING(setappdata)

@DOCSTRING(getappdata)

@DOCSTRING(rmappdata)

@DOCSTRING(isappdata)

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

@DOCSTRING(hggroup)

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.

@DOCSTRING(addproperty)

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.

@DOCSTRING(addlistener)

@DOCSTRING(dellistener)

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

@DOCSTRING(linkprop)

@DOCSTRING(linkaxes)

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.

@DOCSTRING(refreshdata)

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

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

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

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

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

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

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

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

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

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

@table @code
@item  showbaseline
@itemx baseline
@itemx basevalue
The property @code{showbaseline} flags whether the baseline of the bar
series is displayed (default is @qcode{"on"}).  The handle of the graphics
object representing the baseline is given by the @code{baseline} property and
the y-value of the baseline by the @code{basevalue} property.

Changes to any of these properties are propagated to the other members of
the bar series and to the baseline itself.  Equally, changes in the
properties of the base line itself are propagated to the members of the
corresponding bar series.

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

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

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

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

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

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

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

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

Contour group objects are created by the @code{contour}, @code{contourf}, and
@code{contour3} functions.  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.

@DOCSTRING(hgtransform)

@c @DOCSTRING(makehgtform)

@node Graphics Toolkits
@subsection Graphics Toolkits
@cindex graphics toolkits
@cindex toolkits, graphics

@DOCSTRING(graphics_toolkit)

@DOCSTRING(available_graphics_toolkits)

@DOCSTRING(loaded_graphics_toolkits)

@DOCSTRING(register_graphics_toolkit)

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

@DOCSTRING(gnuplot_binary)

@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

On Windows platforms, Octave uses software rendering for the OpenGL graphics
toolkits (@qcode{"qt"} and @qcode{"fltk"}) by default.  This is done to avoid
rendering and printing issues due to imperfect OpenGL driver implementations
for diverse graphic cards from different vendors.  As a down-side, software
rendering might be considerably slower than hardware accelerated rendering.
To permanently switch back to hardware accelerated rendering with your graphic
card drivers, rename the following file while Octave is closed:

@file{@var{octave-home}\bin\opengl32.dll}
@*where @var{octave-home} is the directory in which Octave is installed (the
default is @file{C:\Octave\Octave-@var{version}}).

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