Plotting
********

Introduction to Plotting
========================

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

The function call graphics_toolkit ("fltk") selects the FLTK/OpenGL system, and graphics_toolkit ("gnuplot") selects the gnuplot system.  The two systems may be used selectively through the use of the graphics_toolkit property of the graphics handle for each figure.  This is explained in Graphics Data Structures.

High-Level Plotting
===================

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 Graphics Data Structures and Advanced Plotting.

Two-Dimensional Plots
---------------------

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

     x = -10:0.1:10;
     plot (x, sin (x));

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

Figure: Simple Two-Dimensional Plot.

(plot)

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

(plotyy)

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

(semilogx)

(semilogy)

(loglog)

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

     hist (randn (10000, 1), 30);

produces the histogram of 10,000 normally distributed random numbers shown in fig:hist.

Figure: Histogram.

(bar)

(barh)

(hist)

(stairs)

(stem)

(stem3)

(scatter)

(plotmatrix)

(pareto)

(rose)

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

(contour)

(contourf)

(contourc)

(contour3)

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

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

produces the figure shown in fig:errorbar.

Figure: Errorbar plot.

(errorbar)

(semilogxerr)

(semilogyerr)

(loglogerr)

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

     polar (0:0.1:10*pi, 0:0.1:10*pi);

produces the spiral plot shown in fig:polar.

Figure: Polar plot.

(polar)

(pie)

(pie3)

(quiver)

(quiver3)

(compass)

(feather)

(pcolor)

(area)

(comet)

(comet3)

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.

(axis)

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

(caxis)

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

(xlim)

Two-dimensional Function Plotting
.................................

Octave can plot a function from a function handle inline function or string defining the function without the user needing to explicitly create the data to be plotted.  The function 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,

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

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

(fplot)

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

(ezplot)

(ezcontour)

(ezcontourf)

(ezpolar)

Three-Dimensional Plotting
--------------------------

The function mesh produces mesh surface plots.  For example,

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

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

Figure: Mesh plot.

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

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

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

displays the spiral in three dimensions shown in fig:plot3.

Figure: Three-dimensional spiral.

Finally, the view function changes the viewpoint for three-dimensional plots.

(mesh)

(meshc)

(meshz)

(hidden)

(surf)

(surfc)

(surfl)

(surfnorm)

(diffuse)

(specular)

(meshgrid)

(ndgrid)

(plot3)

(view)

(slice)

(ribbon)

(shading)

(scatter3)

Three-dimensional Function Plotting
...................................

(ezplot3)

(ezmesh)

(ezmeshc)

(ezsurf)

(ezsurfc)

Three-dimensional Geometric Shapes
..................................

(cylinder)

(sphere)

(ellipsoid)

Plot Annotations
----------------

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

     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)");

The functions grid and 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.

(title)

(legend)

(text)

See Text Properties for the properties that you can set.

(xlabel)

(clabel)

(box)

(grid)

(colorbar)

Multiple Plots on One Page
--------------------------

Octave can display more than one plot in a single figure.  The simplest way to do this is to use the subplot function to divide the plot area into a series of subplot windows that are indexed by an integer. For example,

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

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

(subplot)

Multiple Plot Windows
---------------------

You can open multiple plot windows using the figure function. For example,

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

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

(figure)

Use of axis, line, and patch functions
--------------------------------------

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

(axes) (line) (patch)

(fill)

(surface)

Manipulation of plot windows
----------------------------

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

(drawnow)

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

(refresh)

Normally, high-level plot functions like plot or mesh call newplot to initialize the state of the current axes so that the next plot is drawn in a blank window with default property settings.  To have two plots superimposed over one another, use the hold function.  For example,

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

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.

(newplot)

(hold)

(ishold) To clear the current figure, call the clf function.  To clear the current axis, call the cla function.  To bring the current figure to the top of the window stack, call the shg function.  To delete a graphics object, call delete on its index.  To close the figure window, call the close function.

(clf)

(cla)

(shg)

(delete)

(close)

(closereq)

Use of the interpreter Property
-------------------------------

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

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

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

  \bf   Bold font
  \it   Italic font
  \sl   Oblique Font
  \rm   Normal font

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

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

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

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

  \fontname{FONTNAME}   Specify the font to use
  \fontsize{SIZE}   Specify the size of the font to
use

Finally, the superscript and subscripting can be controlled with the '^' and '_' characters.  If the '^' or '_' is followed by a { character, then all of the block surrounded by the { } pair is super- or sub-scripted.  Without the { } pair, only the character immediately following the '^' or '_' is super- or sub-scripted.

   \forall        \exists        \ni
   \cong          \Delta         \Phi
   \Gamma         \vartheta      \Lambda
   \Pi            \Theta         \Sigma
   \varsigma      \Omega         \Xi
   \Psi           \perp          \alpha
   \beta          \chi           \delta
   \epsilon       \phi           \gamma
   \eta           \iota          \varphi
   \kappa         \lambda        \mu
   \nu            \o             \pi
   \theta         \rho           \sigma
   \tau           \upsilon       \varpi
   \omega         \xi            \psi
   \zeta          \sim           \Upsilon
   \prime         \leq           \infty
   \clubsuit      \diamondsuit       \heartsuit
   \spadesuit     \leftrightarrow    \leftarrow
   \uparrow       \rightarrow    \downarrow
   \circ         \pm             \geq
   \times         \propto        \partial
   \bullet       \div            \neq
   \equiv         \approx        \ldots
   \mid           \aleph         \Im
   \Re           \wp             \otimes
   \oplus        \oslash         \cap
   \cup            \supset       \supseteq
   \subset       \subseteq       \in
   \notin        \angle          \bigrightriangledown
   \langle        \rangle        \nabla
   \prod         \surd           \cdot
   \neg           \wedge        \vee
   \Leftrightarrow   \Leftarrow   \Uparrow
   \Rightarrow   \Downarrow     \diamond
   \copyright     \lfloor        \lceil
   \rfloor        \rceil         \int

Table: Available special characters in TeX mode

A complete example showing the capabilities of the extended text is

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

Printing and Saving Plots
-------------------------

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

     print -deps foo.eps

writes the current figure to an encapsulated PostScript file called foo.eps.

(print)

(saveas)

(orient)

Interacting with Plots
----------------------

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

(ginput)

(waitforbuttonpress)

(gtext)

Test Plotting Functions
-----------------------

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

(sombrero)

(peaks)

Graphics Data Structures
========================

Introduction to Graphics Structures
-----------------------------------

The graphics functions use pointers, which are of class graphics_handle, in order to address the data structures which control graphical displays.  A graphics handle may point any one of a number of different object types.  The objects are the graphics data structures.  The types of objects are: figure, axes, line, text, patch, surface, text and image.

Each of these objects has a function by the same name. and, each of these functions returns a graphics handle pointing to an object of corresponding type.  In addition there are several functions which operate on properties of the graphics objects and which return handles: the functions  plot and plot3 return a handle pointing to an object of type line, the function subplot returns a handle pointing to an object of type axes, the function fill returns a handle pointing to an object of type patch, the functions area, bar, barh, contour, contourf, contour3, surf, mesh, surfc, meshc, errorbar, quiver, quiver3, scatter, scatter3, stair, stem, stem3 each return a handle as documented in Data Sources.

The graphics objects are arranged in a hierarchy:

1. The root is at 0.  i.e., get (0) returns the properties of the root object.

2. Below the root are figure objects.

3. Below the figure objects are axes.

4. Below the axes objects are line, text, patch, surface, and image objects.

Graphics handles may be distinguished from function handles (Function Handles) by means of the function ishandle.  ishandle returns true if its argument is a handle of a graphics object.  In addition, the figure object may be tested using isfigure.  isfigure returns true only if its argument is a handle of a figure. ishghandle() is synonymous with ishandle().  The whos function can be used to show the object type of each currently defined graphics handle.  (Note: this is not true today, but it is, I hope, considered an error in whos.  It may be better to have whos just show graphics_handle as the class, and provide a new function which, given a graphics handle, returns its object type.  This could generalize the ishandle() functions and, in fact, replace them.)

The get and set commands are used to obtain and set the values of properties of graphics objects.  In addition, the get command may be used to obtain property names.

For example, the property "type" of the graphics object pointed to by the graphics handle h may be displayed by:

     get (h, "type")

The properties and their current values are returned by get (h) where h is a handle of a graphics object.  If only the names of the allowed properties are wanted they may be displayed by: get (h, "").

Thus, for example,

     h = figure ();
     get (h, "type")
     ans = figure
     get (h, "");
     error: get: ambiguous figure property name ; possible matches:

     __graphics_toolkit__  hittest              resize
     __enhanced__          integerhandle        resizefcn
     __modified__          interruptible        selected
     __myhandle__          inverthardcopy       selectionhighlight
     __plot_stream__       keypressfcn          selectiontype
     alphamap              keyreleasefcn        tag
     beingdeleted          menubar              toolbar
     busyaction            mincolormap          type
     buttondownfcn         name                 uicontextmenu
     children              nextplot             units
     clipping              numbertitle          userdata
     closerequestfcn       paperorientation     visible
     color                 paperposition        windowbuttondownfcn
     colormap              paperpositionmode    windowbuttonmotionfcn
     createfcn             papersize            windowbuttonupfcn
     currentaxes           papertype            windowbuttonwheelfcn
     currentcharacter      paperunits           windowstyle
     currentobject         parent               wvisual
     currentpoint          pointer              wvisualmode
     deletefcn             pointershapecdata    xdisplay
     dockcontrols          pointershapehotspot  xvisual
     doublebuffer          position             xvisualmode
     filename              renderer
     handlevisibility      renderermode

The root figure has index 0.  Its properties may be displayed by: get (0, "").

The uses of get and set are further explained in get, set.

(isprop)

Graphics Objects
----------------

The hierarchy of graphics objects was explained above.  (See 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 handle.

root figure
     the top level of the hierarchy and the parent of all figure objects. The handle index of the root figure is 0.

figure
     A figure window.

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

line
     A line in two or three dimensions.

text
     Text annotations.

image
     A bitmap image.

patch
     A filled polygon, currently limited to two dimensions.

surface
     A three-dimensional surface.

Handle Functions
................

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

(ishandle)

(ishghandle)

(isfigure)

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

(gcf)

(gca)

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

     get (0)
         => ans =
            {
              type = root
              currentfigure = [](0x0)
              children = [](0x0)
              visible = on
              ...
            }

returns a structure containing all the properties of the root figure. As with all functions in Octave, the structure is returned by value, so modifying it will not modify the internal root figure plot object.  To do that, you must use the set function.  Also, note that in this case, the currentfigure property is empty, which indicates that there is no current figure window.

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

     get (gca (), "xlim")
         => [ 0 1 ]

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,

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

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

     set (gca ())

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

(get)

(set)

(ancestor)

(allchild)

Graphics Object Properties
--------------------------

In this Section the object properties are discussed in detail, starting with the root figure properties and continuing through the graphics object hierarchy.

Root Figure Properties
......................

The root figure properties are:

__modified__
     --- Values: "on," "off"

__myhandle__

beingdeleted
     --- Values: "on," "off"

busyaction

buttondownfcn

callbackobject

children

clipping
     --- Values: "on," "off"

createfcn

currentfigure

deletefcn

handlevisibility
     --- Values: "on," "off"

hittest
     --- Values: "on," "off"

interruptible
     --- Values: "on," "off"

parent

screendepth

screenpixelsperinch

screensize

selected

selectionhighlight

screendepth

screenpixelsperinch

showhiddenhandles
     --- Values: "on," "off"

tag

type

uicontextmenu

units

userdata

visible

Figure Properties
.................

The figure properties are:

__graphics_toolkit__
     --- The graphics toolkit currently in use.

__enhanced__

__modified__

__myhandle__

__plot_stream__

alphamap

beingdeleted
     --- Values: "on," "off"

busyaction

buttondownfcn

children
     Handle to children.

clipping
     --- Values: "on," "off"

closerequestfcn
     --- Handle of function to call on close.

color

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

paperorientation

createfcn

currentaxes
     Handle to graphics object of current axes.

currentcharacter

currentobject

currentpoint
     Holds the coordinates of the point over which the mouse pointer was when the mouse button was pressed.  If a mouse callback function is defined, "currentpoint" holds the coordinates of the point over which the mouse pointer is when the function gets called.

deletefcn

dockcontrols
     --- Values: "on," "off"

doublebuffer
     --- Values: "on," "off"

filename

handlevisibility
     --- Values: "on," "off"

hittest

integerhandle

interruptible
     --- Values: "on," "off"

inverthardcopy

keypressfcn
     see "keypressfcn"

keyreleasefcn
     With "keypressfcn", The keyboard callback functions.  These callback functions get called when a key is pressed/released respectively.  The functions are called with two input arguments.  The first argument holds the handle of the calling figure.  The second argument holds the event structure which has the following members:

     Character
          The ASCII value of the key

     Key
          lowercase value of the key

     Modifier
          A cell array containing strings representing the modifiers pressed with the key.  Possible values are "shift", "alt", and "control".

menubar

mincolormap

name

nextplot
     May be one of

     "new"

     "add"

     "replace"

     "replacechildren"

numbertitle

paperorientation
     Indicates the orientation for printing.  Either "landscape" or "portrait".

paperposition

paperpositionmode

papersize

papertype

paperunits

pointer

pointershapecdata

pointershapehotspot

position

renderer

renderermode

resize

resizefcn

selected

selectionhighlight
     --- Values: "on," "off"

selectiontype

tag

toolbar

type

units

userdata

visible
     Either "on" or "off" to toggle display of the figure.

windowbuttondownfcn
     See "windowbuttonupfcn"

windowbuttonmotionfcn
     See "windowbuttonupfcn"

windowbuttonupfcn
     With "windowbuttondownfcn" and "windowbuttonmotionfcn", The mouse callback functions.  These callback functions get called when the mouse button is pressed, dragged, and released respectively.  When these callback functions are called, the "currentpoint" property holds the current coordinates of the cursor.

windowbuttonwheelfcn

windowstyle

wvisual

wvisualmode

xdisplay

xvisual

xvisualmode

Axes Properties
...............

The axes properties are:

__modified__

__myhandle__

activepositionproperty

alim

alimmode

ambientlightcolor

beingdeleted

box
     Box surrounding axes. --- Values: "on," "off"

busyaction

buttondownfcn

cameraposition

camerapositionmode

cameratarget

cameratargetmode

cameraupvector

cameraupvectormode

cameraviewangle

cameraviewanglemode

children

clim
     Two-element vector defining the limits for the c axis of an image.  See pcolor property. Setting this property also forces the corresponding mode property to be set to "manual".

climmode
     Either "manual" or "auto".

clipping

color

colororder

createfcn

currentpoint
     Holds the coordinates of the point over which the mouse pointer was when the mouse button was pressed.  If a mouse callback function is defined, "currentpoint" holds the coordinates of the point over which the mouse pointer is when the function gets called.

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

dataaspectratiomode
     Either "manual" or "auto".

deletefcn

drawmode

fontangle

fontname

fontsize

fontunits

fontweight

gridlinestyle

handlevisibility

hittest

interpreter

interruptible

key
     Toggle display of the legend.  --- Values: "on," "off" Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

keybox
     Toggle display of a box around the legend.  --- Values: "on," "off" Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

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

keyreverse

layer

linestyleorder

linewidth

minorgridlinestyle

nextplot
     May be one of

     "new"

     "add"

     "replace"

     "replacechildren"

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

parent

plotboxaspectratio

plotboxaspectratiomode

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

projection

selected

selectionhighlight

tag

tickdir

tickdirmode

ticklength

tightinset

title
     Index of text object for the axes title.

type

uicontextmenu

units

userdata

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

visible
     Either "on" or "off" to toggle display of the axes.

x_normrendertransform

x_projectiontransform

x_rendertransform

x_viewporttransform

x_viewtransform

xaxislocation
     Either "top" or "bottom".

xcolor

xdir
     Either "forward" or "reverse".

xgrid
     Either "on" or "off" to toggle display of grid lines.

xlabel
     Indices to text objects for the axes labels.

xlim
     Two-element vector defining the limits for the x-axis. Setting this property also forces the corresponding mode property to be set to "manual".

xlimmode
     Either "manual" or "auto".

xminorgrid
     Either "on" or "off" to toggle display of minor grid lines.

xminortick

xscale
     Either "linear" or "log".

xtick
     Set position of tick marks. Setting this property also forces the corresponding mode property to be set to "manual".

xticklabel
     Setting this property also forces the corresponding mode property to be set to "manual".

xticklabelmode
     Either "manual" or "auto".

xtickmode
     Either "manual" or "auto".

yaxislocation
     Either "left" or "right"

ycolor

ydir
     Either "forward" or "reverse".

ygrid
     Either "on" or "off" to toggle display of grid lines.

ylabel
     Indices to text objects for the axes labels.

ylim
     Two-element vectors defining the limits for the x, y, and z axes and the Setting one of these properties also forces the corresponding mode property to be set to "manual".

ylimmode
     Either "manual" or "auto".

yminorgrid
     Either "on" or "off" to toggle display of minor grid lines.

yminortick

yscale
     Either "linear" or "log".

ytick
     Set position of tick marks. Setting this property also forces the corresponding mode property to be set to "manual".

yticklabel
     Setting this property also forces the corresponding mode property to be set to "manual".

yticklabelmode
     Either "manual" or "auto".

ytickmode
     Either "manual" or "auto".

zcolor

zdir
     Either "forward" or "reverse".

zgrid
     Either "on" or "off" to toggle display of grid lines.

zlabel
     Indices to text objects for the axes labels.

zlim
     Two-element vector defining the limits for z-axis. Setting this property also forces the corresponding mode property to be set to "manual".

zlimmode
     Either "manual" or "auto".

zminorgrid
     Either "on" or "off" to toggle display of minor grid lines.

zminortick

zscale
     Either "linear" or "log".

ztick
     Set position of tick marks. Setting this property also forces the corresponding mode property to be set to "manual".

zticklabel
     Setting this property also forces the corresponding mode property to be set to "manual".

zticklabelmode
     Either "manual" or "auto".

ztickmode
     Either "manual" or "auto".

Line Properties
...............

The line properties are:

__modified__

__myhandle__

beingdeleted

busyaction

buttondownfcn

children

clipping

color
     The RGB color of the line, or a color name.  See Colors.

createfcn

deletefcn

displayname

erasemode

handlevisibility

hittest

interpreter

interruptible

keylabel
     The text of the legend entry corresponding to this line.  Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

ldata
     The lower errorbar in the y direction to be plotted.

linestyle
linewidth
     See Line Styles.

linewidth

marker

markeredgecolor

markerfacecolor

markersize
     See Marker Styles.

parent

selected

selectionhighlight

tag

type

udata
     The upper errorbar in the y direction to be plotted.

uicontextmenu

userdata

visible

xdata
     The data to be plotted.

xdatasource

xldata
     The lower errorbar to be plotted.

xlim

xliminclude

xudata
     The upper errorbar to be plotted.

ydata
     The data to be plotted.

ydatasource

ylim

yliminclude

zdata
     The data to be plotted.

zdatasource

zlim

zliminclude

Text Properties
...............

The text properties are:

__modified__

__myhandle__

backgroundcolor

beingdeleted

busyaction

buttondownfcn

children

clipping

color
     The color of the text.  See Colors.

createfcn

deletefcn

displayname

edgecolor

editing

erasemode

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

fontname
     The font used for the text.

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

fontunits

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

handlevisibility

hittest

horizontalalignment
     May be "left", "center", or "right".

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

interruptible

linestyle

linewidth

margin

parent

position
     The coordinates of the text object.

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

selected

selectionhighlight

string
     The character string contained by the text object.

tag

type

uicontextmenu

units
     May be "normalized" or "graph".

userdata

verticalalignment

visible

xlim

xliminclude

ylim

yliminclude

zlim

zliminclude

Image Properties
................

The image properties are:

__modified__

__myhandle__

beingdeleted

busyaction

buttondownfcn

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

cdatamapping

children

clim

climinclude

clipping

createfcn

deletefcn

handlevisibility

hittest

interruptible

parent

selected

selectionhighlight

tag

type

uicontextmenu

userdata

visible

xdata
     Two-element vector specifying the range of the x-coordinates for the image.

xlim

xliminclude

ydata
     Two-element vector specifying the range of the y-coordinates for the image.

ylim

yliminclude

Patch Properties
................

The patch properties are:

__modified__

__myhandle__

alim

aliminclude

alphadatamapping

ambientstrength

backfacelighting

beingdeleted

busyaction

buttondownfcn

cdata
     Data defining the patch object.

cdatamapping

children

clim

climinclude

clipping

createfcn

deletefcn

diffusestrength

edgealpha

edgecolor
     The color of the line defining the patch.  See Colors.

edgelighting

erasemode

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

facecolor
     The fill color of the patch.  See Colors.

facelighting

faces

facevertexalphadata

facevertexcdata

handlevisibility

hittest

interpreter

interruptible

keylabel

linestyle
     See Line Styles.

linewidth
     See Line Styles.

marker
     See Marker Styles.

markeredgecolor
     See Marker Styles.

markerfacecolor
     See Marker Styles.

markersize
     See Marker Styles.

normalmode

parent

selected

selectionhighlight

specularcolorreflectance

specularexponent

specularstrength

tag

type

uicontextmenu

userdata

vertexnormals

vertices

visible

xdata
     Data defining the patch object.

xlim

xliminclude

ydata
     Data defining the patch object.

ylim

yliminclude

zdata
     Data defining the patch object.

zlim

zliminclude

Surface Properties
..................

The surface properties are:

__modified__

__myhandle__

alim

aliminclude

alphadata

alphadatamapping

ambientstrength

backfacelighting

beingdeleted

busyaction

buttondownfcn

cdata

cdatamapping

cdatasource

children

clim

climinclude

clipping

createfcn

deletefcn

diffusestrength

edgealpha

edgecolor

edgelighting

erasemode

facealpha

facecolor

facelighting

handlevisibility

hittest

interpreter

interruptible

keylabel
     The text of the legend entry corresponding to this surface.  Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

linestyle

linewidth

marker

markeredgecolor

markerfacecolor

markersize

meshstyle

normalmode

parent

selected

selectionhighlight

specularcolorreflectance

specularexponent

specularstrength

tag

type

uicontextmenu

userdata

vertexnormals

visible

xdata
     The data determining the surface.  The xdata and ydata elements are vectors and zdata must be a matrix.

xdatasource

xlim

xliminclude

ydata
     The data determining the surface.  The xdata and ydata elements are vectors and zdata must be a matrix.

ydatasource

ylim

yliminclude

zdata
     The data determining the surface.  The xdata and ydata elements are vectors and zdata must be a matrix.

zdatasource

zlim

zliminclude

Searching Properties
--------------------

(findobj)

(findall)

Managing Default Properties
---------------------------

Object properties have two classes of default values, factory defaults (the initial values) and user-defined defaults, which may override the factory defaults.

Although default values may be set for any object, they are set in parent objects and apply to child objects.  For example,

     set (0, "defaultlinecolor", "green");

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

     default + OBJECT-TYPE + PROPERTY-NAME

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

The example above used the root figure object, 0, so the default property value will apply to all line objects.  However, default values are hierarchical, so defaults set in a figure objects override those set in the root figure object.  Likewise, defaults set in axes objects override those set in figure or root figure objects.  For example,

     subplot (2, 1, 1);
     set (0, "defaultlinecolor", "red");
     set (1, "defaultlinecolor", "green");
     set (gca (), "defaultlinecolor", "blue");
     line (1:10, rand (1, 10));
     subplot (2, 1, 2);
     line (1:10, rand (1, 10));
     figure (2)
     line (1:10, rand (1, 10));

produces two figures.  The line in first subplot window of the first figure is blue because it inherits its color from its parent axes object.  The line in the second subplot window of the first figure is green because it inherits its color from its parent figure object.  The line in the second figure window is red because it inherits its color from the global root figure parent object.

To remove a user-defined default setting, set the default property to the value "remove".  For example,

     set (gca (), "defaultlinecolor", "remove");

removes the user-defined default line color setting from the current axes object.  To quickly remove all user-defined defaults use the reset function.

(reset)

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

     get (gca (), "default");

returns a list of user-defined default values for the current axes object.

Factory default values are stored in the root figure object.  The command

     get (0, "factory");

returns a list of factory defaults.

Advanced Plotting
=================

Colors
------

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

Line Styles
-----------

Line styles are specified by the following properties:

linestyle
     May be one of

     "-"
          Solid lines.

     "--"
          Dashed lines.

     ":"
          Points.

     "-."
          A dash-dot line.

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.

Marker Styles
-------------

Marker styles are specified by the following properties:

marker
     A character indicating a plot marker to be place at each data point, or "none", meaning no markers should be displayed.

markeredgecolor
     The color of the edge around the marker, or "auto", meaning that the edge color is the same as the face color.  See Colors.

markerfacecolor
     The color of the marker, or "none" to indicate that the marker should not be filled.  See Colors.

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.

Callbacks
---------

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

     function mycallback (src, data)
     ...
     endfunction

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

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

where at the moment that the plot is deleted, the message "Window Deleted" will be displayed.

Additional user arguments can be passed to callback functions, and will be passed after the 2 default arguments.  For example:

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

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

  * CreateFcn This is the callback that is called at the moment of the objects creation.  It is not called if the object is altered in any way, and so it only makes sense to define this callback in the function call that defines the object.  Callbacks that are added to CreateFcn later with the set function will never be executed.

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

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

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

(gcbo)

(gcbf)

Callbacks can equally be added to properties with the addlistener function described below.

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 hggroup

(hggroup)

For example a simple use of a hggroup might be

     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");

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

(addproperty)

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

(addlistener)

(dellistener)

An example of the use of these two functions might be

     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

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

     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");

(linkprop)

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

  * group together multiple graphics objects,

  * create linked properties between different graphics objects, and

  * to hide the nominal user data, from the actual data of the objects.

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

     h = stem (1:4)
     get (h, "xdata")
     => [  1   2   3   4]'
     get (get (h, "children")(1), "xdata")
     => [  1   1 NaN   2   2 NaN   3   3 NaN   4   4 NaN]'

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

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 refreshdata function is called.

(refreshdata)

Area Series
...........

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

basevalue
     The value where the base of the area plot is drawn.

linewidth
linestyle
     The line width and style of the edge of the patch objects making up the areas.  See Line Styles.

edgecolor
facecolor
     The line and fill color of the patch objects making up the areas. See Colors.

xdata
ydata
     The x and y coordinates of the original columns of the data passed to area prior to the cumulative summation used in the area function.

xdatasource
ydatasource
     Data source variables.

Bar Series
..........

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

showbaseline
baseline
basevalue
     The property showbaseline flags whether the baseline of the bar series is displayed (default is "on").  The handle of the graphics object representing the baseline is given by the baseline property and the y-value of the baseline by the basevalue property.

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

barwidth
barlayout
horizontal
     The property barwidth is the width of the bar corresponding to the WIDTH variable passed to bar or BARH.  Whether the bar series is "grouped" or "stacked" is determined by the barlayout property and whether the bars are horizontal or vertical by the horizontal property.

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

linewidth
linestyle
     The line width and style of the edge of the patch objects making up the bars.  See Line Styles.

edgecolor
facecolor
     The line and fill color of the patch objects making up the bars.  See Colors.

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

ydata
     The y value of the bars in the hggroup.

xdatasource
ydatasource
     Data source variables.

Contour Groups
..............

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

contourmatrix
     A read only property that contains the data return by contourc used to create the contours of the plot.

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

zlevelmode
zlevel
     The radio property zlevelmode can have the values "none", "auto" or "manual".  When its value is "none" there is no z component to the plotted contours.  When its value is "auto" the z value of the plotted contours is at the same value as the contour itself.  If the value is "manual", then the z value at which to plot the contour is determined by the zlevel property.

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

textlistmode
textlist
textstepmode
textstep
     If textlistmode is "manual", then the labeled contours is determined by textlist.  If textlistmode is set to "auto", then the distance between labeled contours is determined by textstep.  If both textlistmode and textstepmode are set to "auto", then there are assumed to be 10 equal spaced labeled contours.

showtext
     Flag whether the contour labels are shown or not.

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

linewidth

linestyle

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

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

xdatasource
ydatasource
zdatasource
     Data source variables.

Error Bar Series
................

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

color
     The RGB color or color name of the line objects of the error bars. See Colors.

linewidth
linestyle
     The line width and style of the line objects of the error bars.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the error bars.  See Colors.

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

xdatasource
ydatasource
ldatasource
udatasource
xldatasource
xudatasource
     Data source variables.

Line Series
...........

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

color
     The RGB color or color name of the line objects.  See Colors.

linewidth
linestyle
     The line width and style of the line objects.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers.  See Colors.

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

xdatasource
ydatasource
zdatasource
     Data source variables.

Quiver Group
............

Quiver series objects are created by the quiver or quiver3 functions.  Each 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

autoscale
autoscalefactor
     Flag whether the length of the arrows is scaled or defined directly from the U, V and W data.  If the arrow length is flagged as being scaled by the autoscale property, then the length of the autoscaled arrow is controlled by the autoscalefactor.

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

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

color
     The RGB color or color name of the line objects of the quiver.  See Colors.

linewidth
linestyle
     The line width and style of the line objects of the quiver.  See Line Styles.

marker
markerfacecolor
markersize
     The line and fill color of the marker objects at the original of the arrows.  See Colors.

xdata
ydata
zdata
     The origins of the values of the vector field.

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

xdatasource
ydatasource
zdatasource
udatasource
vdatasource
wdatasource
     Data source variables.

Scatter Group
.............

Scatter series objects are created by the scatter or scatter3 functions.  A single hggroup element contains as many children as there are points in the scatter plot, with each child representing one of the points. The properties of the stem series are

linewidth
     The line width of the line objects of the points.  See Line Styles.

marker
markeredgecolor
markerfacecolor
     The line and fill color of the markers of the points.  See Colors.

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

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

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

xdatasource
ydatasource
zdatasource
cdatasource
sizedatasource
     Data source variables.

Stair Group
...........

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

color
     The RGB color or color name of the line objects of the stairs.  See Colors.

linewidth
linestyle
     The line width and style of the line objects of the stairs.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the stairs.  See Colors.

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

xdatasource
ydatasource
     Data source variables.

Stem Series
...........

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

showbaseline
baseline
basevalue
     The property showbaseline flags whether the baseline of the stem series is displayed (default is "on").  The handle of the graphics object representing the baseline is given by the baseline property and the y-value (or z-value for stem3) of the baseline by the 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.

color
     The RGB color or color name of the line objects of the stems.  See Colors.

linewidth
linestyle
     The line width and style of the line objects of the stems.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the stems.  See Colors.

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

xdatasource
ydatasource
zdatasource
     Data source variables.

Surface Group
.............

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

The properties of the surface group are

edgecolor

facecolor
     The RGB color or color name of the edges or faces of the surface. See Colors.

linewidth
linestyle
     The line width and style of the lines on the surface.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the surface.  See Colors.

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

xdatasource
ydatasource
zdatasource
cdatasource
     Data source variables.

Graphics Toolkits
-----------------

(graphics_toolkit)

(available_graphics_toolkits)

Customizing Toolkit Behavior
............................

The specific behavior of the backend toolkit may be modified using the following utility functions.  Note: Not all functions apply to every graphics toolkit.

(gnuplot_binary)

(gui_mode)

(mouse_wheel_zoom)