15.2 Advanced Plotting

15.2.1 Graphics Objects

Plots in Octave are constructed from the following graphics objects. Each graphics object has a set of properties that define its appearance and may also contain links to other graphics objects. Graphics objects are only referenced by a numeric index, or handle.

root figure

The parent of all figure objects. The index for the root figure is defined to be 0.

figure

A figure window.

axes

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

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

Built-in Function: ishandle (h)

Return true if h is a graphics handle and false otherwise.

Function File: isfigure (h)

Return true if h is a graphics handle that contains a figure object and false otherwise.

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.

Function File: gcf ()

Return the current figure handle. If a figure does not exist, create one and return its handle. The handle may then be used to examine or set properties of the figure. For example,

fplot (@sin, [-10, 10]); fig = gcf (); set (fig, "visible", "off");

plots a sine wave, finds the handle of the current figure, and then makes that figure invisible. Setting the visible property of the figure to "on" will cause it to be displayed again.
See also: get, set.

Function File: gca ()

Return a handle to the current axis object. If no axis object exists, create one and return its handle. The handle may then be used to examine or set properties of the axes. For example,

ax = gca (); set (ax, "position", [0.5, 0.5, 0.5, 0.5]);

creates an empty axes object, then changes its location and size in the figure window.
See also: get, set.

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

get (0)
    ⇒ ans =
       {
         type = root figure
         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.

Built-in Function: get (h, p)

Return the named property p from the graphics handle h. If p is omitted, return the complete property list for h. If h is a vector, return a cell array including the property values or lists respectively.

Built-in Function: set (h, p, v, …)

Set the named property value or vector p to the value v for the graphics handle h.

Function File: parent = ancestor (h, type)

Function File: parent = ancestor (h, type, 'toplevel')

Return the first ancestor of handle object h whose type matches type, where type is a character string. If type is a cell array of strings, return the first parent whose type matches any of the given type strings.

If the handle object h is of type type, return h.

If "toplevel" is given as a 3rd argument, return the highest parent in the object hierarchy that matches the condition, instead of the first (nearest) one.
See also: get, set.

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.

Function File: axes ()

Function File: axes (property, value, …)

Function File: axes (h)

Create an axes object and return a handle to it.

Function File: line ()

Function File: line (x, y)

Function File: line (x, y, z)

Function File: line (x, y, z, property, value, …)

Create line object from x and y and insert in current axes object. Return a handle (or vector of handles) to the line objects created.

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

Function File: patch ()

Function File: patch (x, y, c)

Function File: patch (x, y, c, opts)

Function File: patch ('Faces', f, 'Vertices', v, …)

Function File: patch (…, prop, val)

Function File: patch (h, …)

Function File: h = patch (…)

Create patch object from x and y with color c and insert in the current axes object. Return handle to patch object.

For a uniform colored patch, c can be given as an RGB vector, scalar value referring to the current colormap, or string value (for example, "r" or "red").

Function File: surface (x, y, z, c)

Function File: surface (x, y, z)

Function File: surface (z, c)

Function File: surface (z)

Function File: surface (…, prop, val)

Function File: surface (h, …)

Function File: h = surface (…)

Plot a surface graphic object given matrices x, and y from meshgrid and a matrix z corresponding to the x and y coordinates of the surface. If x and y are vectors, then a typical vertex is (x(j), y(i), z(i,j)). Thus, columns of z correspond to different x values and rows of z correspond to different y values. If x and y are missing, they are constructed from size of the matrix z.

Any additional properties passed are assigned the the surface..
See also: surf, mesh, patch, line.

By default, Octave refreshes the plot window when a prompt is printed, or when waiting for input. To force an update at other times, call the drawnow function.

Function File: drawnow ()

Update and display the current graphics.

Octave automatically calls drawnow just before printing a prompt, when sleep or pause is called, or while waiting for command-line input.

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, call 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.

Function File: newplot ()

Prepare graphics engine to produce a new plot. This function should be called at the beginning of all high-level plotting functions.

Function File: hold args

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

hold on

turns the hold state on. An argument of "off" turns the hold state off, and hold with no arguments toggles the current hold state.

Function File: ishold

Return true if the next line will be added to the current plot, or false if the plot device will be cleared before drawing the next line.

To clear the current figure, call the clf function. To bring it 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.

Function File: clf ()

Clear the current figure.
See also: close, delete.

Function File: shg

Show the graph window. Currently, this is the same as executing drawnow.
See also: drawnow, figure.

Function File: delete (file)

Function File: delete (h)

Delete the named file or figure handle.

Command: close

Command: close (n)

Command: close all

Command: close all hidden

Close figure window(s) by calling the function specified by the "closerequestfcn" property for each figure. By default, the function closereq is used.
See also: closereq.

Function File: closereq ()

Close the current figure and delete all graphics objects associated with it.
See also: close, delete.

15.2.2 Graphics Object Properties

15.2.2.1 Root Figure Properties

currentfigure

Index to graphics object for the current figure.

15.2.2.2 Figure Properties

nextplot

May be one of

"new"

"add"

"replace"

"replacechildren"

closerequestfcn

Handle of function to call when a figure is closed.

currentaxes

Index to graphics object of current axes.

colormap

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

visible

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

paperorientation

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

15.2.2.3 Axes Properties

position

A four-element vector specifying the coordinates of the lower left corner and width and height of the plot, in normalized units. 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.

title

Index of text object for the axes title.

box

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

key

Either "on" or "off" to toggle display of the legend. Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

keybox

Either "on" or "off" to toggle display of a box around the legend. 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.

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

xlim

ylim

zlim

clim

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

xlimmode

ylimmode

zlimmode

climmode

Either "manual" or "auto".

xlabel

ylabel

zlabel

Indices to text objects for the axes labels.

xgrid

ygrid

zgrid

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

xminorgrid

yminorgrid

zminorgrid

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

xtick

ytick

ztick

Setting one of these properties also forces the corresponding mode property to be set to "manual".

xtickmode

ytickmode

ztickmode

Either "manual" or "auto".

xticklabel

yticklabel

zticklabel

Setting one of these properties also forces the corresponding mode property to be set to "manual".

xticklabelmode

yticklabelmode

zticklabelmode

Either "manual" or "auto".

xscale

yscale

zscale

Either "linear" or "log".

xdir

ydir

zdir

Either "forward" or "reverse".

xaxislocation

yaxislocation

Either "top" or "bottom" for the x axis and "left" or "right" for the y axis.

view

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

visible

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

nextplot

May be one of

"new"

"add"

"replace"

"replacechildren"

outerposition

A four-element vector specifying the coordinates of the lower left corner and width and height of the plot, in normalized units. 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.

15.2.2.4 Line Properties

xdata

ydata

zdata

ldata

udata

xldata

xudata

The data to be plotted. The ldata and udata elements are for errobars in the y direction, and the xldata and xudata elements are for errorbars in the x direction.

color

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

linestyle

linewidth

See section Line Styles.

marker

markeredgecolor

markerfacecolor

markersize

See section Marker Styles.

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.

15.2.2.5 Text Properties

string

The character string contained by the text object.

units

May be "normalized" or "graph".

position

The coordinates of the text object.

rotation

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

horizontalalignment

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

color

The color of the text. See section Colors.

fontname

The font used for the text.

fontsize

The size of the font, in points to use.

fontangle

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

fontweight

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

interpreter

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

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 formating of the text can be changed within the string with the codes

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

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.

Table 15.1: 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'))

The result of which can be seen in fig:extendedtext

Figure 15.7: Example of inclusion of text with the TEX interpreter

15.2.2.6 Image Properties

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.

xdata

ydata

Two-element vectors specifying the range of the x- and y- coordinates for the image.

15.2.2.7 Patch Properties

cdata

xdata

ydata

zdata

Data defining the patch object.

facecolor

The fill color of the patch. See section Colors.

facealpha

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

edgecolor

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

linestyle

linewidth

See section Line Styles.

marker

markeredgecolor

markerfacecolor

markersize

See section Marker Styles.

15.2.2.8 Surface Properties

xdata

ydata

zdata

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

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.

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

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.

15.2.4 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".

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

15.2.6 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 section Colors.

markerfacecolor

The color of the marker, or "none" to indicate that the marker should not be filled. See section 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.

15.2.7 Interaction with gnuplot

Loadable Function: val = gnuplot_binary ()

Loadable Function: old_val = gnuplot_binary (new_val)

Query or set the name of the program invoked by the plot command. The default value "gnuplot". See section Installing Octave.

Loadable Function: val = gnuplot_use_title_option ()

Loadable Function: old_val = gnuplot_use_title_option (new_val)

If enabled, append `-title "Figure NN"' to the gnuplot command. By default, this feature is enabled if the DISPLAY environment variable is set when Octave starts.

This function is obsolete and will be removed from a future version of Octave.

This document was generated on December, 26 2007 using texi2html 1.76.