octave: Graphics Objects
15.3.2 Graphics Objects
-----------------------
The hierarchy of graphics objects was explained above. 
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, surface, or light 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.
light
A light object used for lighting effects on patches and surfaces.
15.3.2.1 Creating Graphics Objects
..................................
You can create any graphics object primitive by calling the function of
the same name as the object; In other words, ‘figure’, ‘axes’, ‘line’,
‘text’, ‘image’, ‘patch’, ‘surface’, and ‘light’ functions. These
fundamental graphic objects automatically become children of the current
axes object as if ‘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 0.
If this auto-joining feature is not desired then it is important to
call ‘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 ‘line’, use ‘plot’. Or use ‘surf’
instead of ‘surface’. Or use ‘fill’ instead of ‘patch’.
-- : axes ()
-- : axes (PROPERTY, VALUE, ...)
-- : axes (HAX)
-- : H = axes (...)
Create an axes object and return a handle to it, or set the current
axes to HAX.
Called without any arguments, or with PROPERTY/VALUE pairs,
construct a new axes. For accepted properties and corresponding
values, set XREFset.
Called with a single axes handle argument HAX, the function makes
HAX the current axes. It also restacks the axes in the
corresponding figure so that HAX is the first entry in the list of
children. This causes HAX to be displayed on top of any other axes
objects (Z-order stacking).
DONTPRINTYET See also: gca XREFgca, set XREFset, *noteget:
DONTPRINTYET See also: gca XREFgca, set XREFset, get
XREFget.
-- : line ()
-- : line (X, Y)
-- : line (X, Y, PROPERTY, VALUE, ...)
-- : line (X, Y, Z)
-- : line (X, Y, Z, PROPERTY, VALUE, ...)
-- : line (PROPERTY, VALUE, ...)
-- : line (HAX, ...)
-- : H = line (...)
Create line object from X and Y (and possibly Z) and insert in the
current axes.
Multiple property-value pairs may be specified for the line object,
but they must appear in pairs.
If the first argument HAX is an axes handle, then plot into this
axes, rather than the current axes returned by ‘gca’.
The optional return value H is a graphics handle (or vector of
handles) to the line objects created.
DONTPRINTYET See also: image XREFimage, patch XREFpatch, *noteDONTPRINTYET DONTPRINTYET See also: image XREFimage, patch XREFpatch,
rectangle XREFrectangle, surface XREFsurface, *notetext:
DONTPRINTYET DONTPRINTYET See also: image XREFimage, patch XREFpatch,
rectangle XREFrectangle, surface XREFsurface, text
XREFtext.
-- : patch ()
-- : patch (X, Y, C)
-- : patch (X, Y, Z, C)
-- : patch ("Faces", FACES, "Vertices", VERTS, ...)
-- : patch (..., PROP, VAL, ...)
-- : patch (..., PROPSTRUCT, ...)
-- : patch (HAX, ...)
-- : H = patch (...)
Create patch object in the current axes with vertices at locations
(X, Y) and of color C.
If the vertices are matrices of size MxN then each polygon patch
has M vertices and a total of N polygons will be created. If some
polygons do not have M vertices use NaN to represent "no vertex".
If the Z input is present then 3-D patches will be created.
The color argument C can take many forms. To create polygons which
all share a single color use a string value (e.g., "r" for red), a
scalar value which is scaled by ‘caxis’ and indexed into the
current colormap, or a 3-element RGB vector with the precise
TrueColor.
If C is a vector of length N then the ith polygon will have a color
determined by scaling entry C(i) according to ‘caxis’ and then
indexing into the current colormap. More complicated coloring
situations require directly manipulating patch property/value
pairs.
Instead of specifying polygons by matrices X and Y, it is possible
to present a unique list of vertices and then a list of polygon
faces created from those vertices. In this case the "Vertices"
matrix will be an Nx2 (2-D patch) or Nx3 (3-D patch). The MxN
"Faces" matrix describes M polygons having N vertices—each row
describes a single polygon and each column entry is an index into
the "Vertices" matrix to identify a vertex. The patch object can
be created by directly passing the property/value pairs
"Vertices"/VERTS, "Faces"/FACES as inputs.
Instead of using property/value pairs, any property can be set by
passing a structure PROPSTRUCT with the respective field names.
If the first argument HAX is an axes handle, then plot into this
axes, rather than the current axes returned by ‘gca’.
The optional return value H is a graphics handle to the created
patch object.
Implementation Note: Patches are highly configurable objects. To
truly customize them requires setting patch properties directly.
Useful patch properties are: "cdata", "edgecolor", "facecolor",
"faces", "facevertexcdata".
DONTPRINTYET See also: fill XREFfill, get XREFget, *noteset:
DONTPRINTYET See also: fill XREFfill, get XREFget, set
XREFset.
-- : surface (X, Y, Z, C)
-- : surface (X, Y, Z)
-- : surface (Z, C)
-- : surface (Z)
-- : surface (..., PROP, VAL, ...)
-- : surface (HAX, ...)
-- : H = surface (...)
Create a surface graphic object given matrices X and Y from
‘meshgrid’ and a matrix of values 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 only a single input
Z is given then X is taken to be ‘1:columns (Z)’ and Y is ‘1:rows
(Z)’.
Any property/value input pairs are assigned to the surface object.
If the first argument HAX is an axes handle, then plot into this
axes, rather than the current axes returned by ‘gca’.
The optional return value H is a graphics handle to the created
surface object.
DONTPRINTYET See also: surf XREFsurf, mesh XREFmesh, *notepatch:
DONTPRINTYET See also: surf XREFsurf, mesh XREFmesh, patch
XREFpatch, line XREFline.
-- : light ()
-- : light (..., "PROP", VAL, ...)
-- : light (HAX, ...)
-- : H = light (...)
Create a light object in the current axes or for axes HAX.
When a light object is present in an axes object, and the
properties "EdgeLighting" or "FaceLighting" of a ‘patch’ or
‘surface’ object are set to a value other than "none", these
objects are drawn with light and shadow effects. Supported values
for Lighting properties are "none" (no lighting effects), "flat"
(faceted look of the objects), and "gouraud" (linear interpolation
of the lighting effects between the vertices). For ‘patch’
objects, the normals must be set manually (property
"VertexNormals").
Up to eight light objects are supported per axes.
Lighting is only supported for OpenGL graphic toolkits (i.e.,
"fltk" and "qt").
A light object has the following properties which alter the
appearance of the plot.
"Color": The color of the light can be passed as an
RGB-vector (e.g., ‘[1 0 0]’ for red) or as a string (e.g., "r"
for red). The default color is white (‘[1 1 1]’).
"Position": The direction from which the light emanates as a
1x3-vector. The default direction is ‘[1 0 1]’.
"Style": This string defines whether the light emanates from a
light source at infinite distance ("infinite") or from a local
point source ("local"). The default is "infinite".
If the first argument HAX is an axes handle, then add the light
object to this axes, rather than the current axes returned by
‘gca’.
The optional return value H is a graphics handle to the created
light object.
DONTPRINTYET See also: lighting XREFlighting, *notematerial:
DONTPRINTYET See also: lighting XREFlighting, material
XREFmaterial, patch XREFpatch, surface XREFsurface.
15.3.2.2 Handle Functions
.........................
To determine whether a variable is a graphics object index, or an index
to an axes or figure, use the functions ‘ishandle’, ‘isaxes’, and
‘isfigure’.
-- : ishandle (H)
Return true if H is a graphics handle and false otherwise.
H may also be a matrix of handles in which case a logical array is
returned that is true where the elements of H are graphics handles
and false where they are not.
See also: isaxes XREFisaxes, isfigure XREFisfigure.
-- : ishghandle (H)
-- : ishghandle (H, TYPE)
Return true if H is a graphics handle (of type TYPE) and false
otherwise.
When no TYPE is specified the function is equivalent to ‘ishandle’.
See also: ishandle XREFishandle.
-- : isaxes (H)
Return true if H is an axes graphics handle and false otherwise.
If H is a matrix then return a logical array which is true where
the elements of H are axes graphics handles and false where they
are not.
See also: isaxes XREFisaxes, ishandle XREFishandle.
-- : isfigure (H)
Return true if H is a figure graphics handle and false otherwise.
If H is a matrix then return a logical array which is true where
the elements of H are figure graphics handles and false where they
are not.
See also: isaxes XREFisaxes, ishandle XREFishandle.
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.
-- : H = gcf ()
Return a handle to the current figure.
The current figure is the default target for graphics output. If
multiple figures exist, ‘gcf’ returns the last created figure or
the last figure that was clicked on with the mouse.
If a current figure does not exist, create one and return its
handle. The handle may then be used to examine or set properties
of the figure. For example,
fplot (@sin, [-10, 10]);
fig = gcf ();
set (fig, "numbertitle", "off", "name", "sin plot")
plots a sine wave, finds the handle of the current figure, and then
renames the figure window to describe the contents.
Note: To find the current figure without creating a new one if it
does not exist, query the "CurrentFigure" property of the root
graphics object.
get (0, "currentfigure");
DONTPRINTYET See also: gca XREFgca, gco XREFgco, *notegcbf:
DONTPRINTYET DONTPRINTYET See also: gca XREFgca, gco XREFgco, gcbf
XREFgcbf, gcbo XREFgcbo, get XREFget, *noteset:
DONTPRINTYET DONTPRINTYET See also: gca XREFgca, gco XREFgco, gcbf
XREFgcbf, gcbo XREFgcbo, get XREFget, set
XREFset.
-- : H = gca ()
Return a handle to the current axes object.
The current axes is the default target for graphics output. In the
case of a figure with multiple axes, ‘gca’ returns the last created
axes or the last axes that was clicked on with the mouse.
If no current axes object exists, create one and return its handle.
The handle may then be used to examine or set properties of the
axes. For example,
ax = gca ();
set (ax, "position", [0.5, 0.5, 0.5, 0.5]);
creates an empty axes object and then changes its location and size
in the figure window.
Note: To find the current axes without creating a new axes object
if it does not exist, query the "CurrentAxes" property of a figure.
get (gcf, "currentaxes");
DONTPRINTYET See also: gcf XREFgcf, gco XREFgco, *notegcbf:
DONTPRINTYET DONTPRINTYET See also: gcf XREFgcf, gco XREFgco, gcbf
XREFgcbf, gcbo XREFgcbo, get XREFget, *noteset:
DONTPRINTYET DONTPRINTYET See also: gcf XREFgcf, gco XREFgco, gcbf
XREFgcbf, gcbo XREFgcbo, get XREFget, set
XREFset.
-- : H = gco ()
-- : H = gco (FIG)
Return a handle to the current object of the current figure, or a
handle to the current object of the figure with handle FIG.
The current object of a figure is the object that was last clicked
on. It is stored in the "CurrentObject" property of the target
figure.
If the last mouse click did not occur on any child object of the
figure, then the current object is the figure itself.
If no mouse click occurred in the target figure, this function
returns an empty matrix.
Programming Note: The value returned by this function is not
necessarily the same as the one returned by ‘gcbo’ during callback
execution. An executing callback can be interrupted by another
callback and the current object may be changed.
DONTPRINTYET See also: gcbo XREFgcbo, gca XREFgca, *notegcf:
DONTPRINTYET DONTPRINTYET See also: gcbo XREFgcbo, gca XREFgca, gcf
XREFgcf, gcbf XREFgcbf, get XREFget, *noteset:
DONTPRINTYET DONTPRINTYET See also: gcbo XREFgcbo, gca XREFgca, gcf
XREFgcf, gcbf XREFgcbf, get XREFget, set
XREFset.
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]’.
Default property values can also be queried if the ‘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,
set (gca ())
returns a structure containing the default property values for axes
objects. If ‘set’ is called with two arguments (a graphic handle and a
property name) then only the defaults for the requested property are
returned.
-- : VAL = get (H)
-- : VAL = get (H, P)
Return the value of 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.
See also: set XREFset.
-- : set (H, PROPERTY, VALUE, ...)
-- : set (H, PROPERTIES, VALUES)
-- : set (H, PV)
-- : VALUE_LIST = set (H, PROPERTY)
-- : ALL_VALUE_LIST = set (H)
Set named property values for the graphics handle (or vector of
graphics handles) H.
There are three ways to give the property names and values:
• as a comma separated list of PROPERTY, VALUE pairs
Here, each PROPERTY is a string containing the property name,
each VALUE is a value of the appropriate type for the
property.
• as a cell array of strings PROPERTIES containing property
names and a cell array VALUES containing property values.
In this case, the number of columns of VALUES must match the
number of elements in PROPERTIES. The first column of VALUES
contains values for the first entry in PROPERTIES, etc. The
number of rows of VALUES must be 1 or match the number of
elements of H. In the first case, each handle in H will be
assigned the same values. In the latter case, the first
handle in H will be assigned the values from the first row of
VALUES and so on.
• as a structure array PV
Here, the field names of PV represent the property names, and
the field values give the property values. In contrast to the
previous case, all elements of PV will be set in all handles
in H independent of the dimensions of PV.
‘set’ is also used to query the list of values a named property
will take. ‘CLIST = set (H, "property")’ will return the list of
possible values for "property" in the cell list CLIST. If no
output variable is used then the list is formatted and printed to
the screen.
If no property is specified (‘SLIST = set (H)’) then a structure
SLIST is returned where the fieldnames are the properties of the
object H and the fields are the list of possible values for each
property. If no output variable is used then the list is formatted
and printed to the screen.
For example,
hf = figure ();
set (hf, "paperorientation")
⇒ paperorientation: [ landscape | {portrait} | rotated ]
shows the paperorientation property can take three values with the
default being "portrait".
See also: get XREFget.
-- : PARENT = ancestor (H, TYPE)
-- : 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 itself is of type TYPE, return H.
If "toplevel" is given as a third argument, return the highest
parent in the object hierarchy that matches the condition, instead
of the first (nearest) one.
See also: findobj XREFfindobj, findall XREFfindall,
allchild XREFallchild.
-- : H = allchild (HANDLES)
Find all children, including hidden children, of a graphics object.
This function is similar to ‘get (h, "children")’, but also returns
hidden objects (HandleVisibility = "off").
If HANDLES is a scalar, H will be a vector. Otherwise, H will be a
cell matrix of the same size as HANDLES and each cell will contain
a vector of handles.
See also: findall XREFfindall, findobj XREFfindobj,
get XREFget, set XREFset.
-- : findfigs ()
Find all visible figures that are currently off the screen and move
them onto the screen.
See also: allchild XREFallchild, figure XREFfigure,
get XREFget, set XREFset.
Figures can be printed or saved in many graphics formats with ‘print’
and ‘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
fig_struct = hdl2struct (gcf);
save myplot.fig -struct fig_struct;
...
fig_struct = load ("myplot.fig");
struct2hdl (fig_struct);
-- : S = hdl2struct (H)
Return a structure, S, whose fields describe the properties of the
object, and its children, associated with the handle, H.
The fields of the structure S are "type", "handle", "properties",
"children", and "special".
DONTPRINTYET See also: struct2hdl XREFstruct2hdl, *notehgsave:
DONTPRINTYET See also: struct2hdl XREFstruct2hdl, hgsave
XREFhgsave, findobj XREFfindobj.
-- : H = struct2hdl (S)
-- : H = struct2hdl (S, P)
-- : H = struct2hdl (S, P, HILEV)
Construct a graphics handle object H from the structure S.
The structure must contain the fields "handle", "type", "children",
"properties", and "special".
If the handle of an existing figure or axes is specified, P, the
new object will be created as a child of that object. If no parent
handle is provided then a new figure and the necessary children
will be constructed using the default values from the root figure.
A third boolean argument HILEV can be passed to specify whether the
function should preserve listeners/callbacks, e.g., for legends or
hggroups. The default is false.
DONTPRINTYET See also: hdl2struct XREFhdl2struct, *notehgload:
DONTPRINTYET See also: hdl2struct XREFhdl2struct, hgload
XREFhgload, findobj XREFfindobj.
-- : HNEW = copyobj (HORIG)
-- : HNEW = copyobj (HORIG, HPARENT)
Construct a copy of the graphic objects associated with the handles
HORIG and return new handles HNEW to the new objects.
If a parent handle HPARENT (root, figure, axes, or hggroup) is
specified, the copied object will be created as a child of HPARENT.
If HORIG is a vector of handles, and HPARENT is a scalar, then each
handle in the vector HNEW has its "Parent" property set to HPARENT.
Conversely, if HORIG is a scalar and HPARENT a vector, then each
parent object will receive a copy of HORIG. If HORIG and HPARENT
are both vectors with the same number of elements then ‘HNEW(i)’
will have parent ‘HPARENT(i)’.
DONTPRINTYET See also: struct2hdl XREFstruct2hdl, *notehdl2struct:
DONTPRINTYET See also: struct2hdl XREFstruct2hdl, hdl2struct
XREFhdl2struct, findobj XREFfindobj.
Info Catalog
octave: Introduction to Graphics Structures
octave: Graphics Data Structures
octave: Graphics Object Properties