This is octave.info, produced by makeinfo version 6.5 from octave.texi.

START-INFO-DIR-ENTRY
* Octave: (octave).           Interactive language for numerical computations.

END-INFO-DIR-ENTRY

   Copyright © 1996-2018 John W. Eaton.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: octave.info,  Node: Interacting with Plots,  Next: Test Plotting Functions,  Prev: Printing and Saving Plots,  Up: High-Level Plotting

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

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

 -- : [X, Y, BUTTONS] = ginput (N)
 -- : [X, Y, BUTTONS] = ginput ()
     Return the position and type of mouse button clicks and/or key
     strokes in the current figure window.

     If N is defined, then capture N events before returning.  When N is
     not defined ‘ginput’ will loop until the return key <RET> is
     pressed.

     The return values X, Y are the coordinates where the mouse was
     clicked in the units of the current axes.  The return value BUTTON
     is 1, 2, or 3 for the left, middle, or right button.  If a key is
     pressed the ASCII value is returned in BUTTON.

     Implementation Note: ‘ginput’ is intenteded for 2-D plots.  For 3-D
     plots see the CURRENTPOINT property of the current axes which can
     be transformed with knowledge of the current ‘view’ into data
     units.

     See also: *note gtext: XREFgtext, *note waitforbuttonpress:
     XREFwaitforbuttonpress.

 -- : waitforbuttonpress ()
 -- : B = waitforbuttonpress ()
     Wait for mouse click or key press over the current figure window.

     The return value of B is 0 if a mouse button was pressed or 1 if a
     key was pressed.

     See also: *note waitfor: XREFwaitfor, *note ginput: XREFginput,
     *note kbhit: XREFkbhit.

 -- : gtext (S)
 -- : gtext ({S1, S2, ...})
 -- : gtext ({S1; S2; ...})
 -- : gtext (..., PROP, VAL, ...)
 -- : H = gtext (...)
     Place text on the current figure using the mouse.

     The text is defined by the string S.  If S is a cell string
     organized as a row vector then each string of the cell array is
     written to a separate line.  If S is organized as a column vector
     then one string element of the cell array is placed for every mouse
     click.

     Optional property/value pairs are passed directly to the underlying
     text objects.

     The optional return value H is a graphics handle to the created
     text object(s).

     See also: *note ginput: XREFginput, *note text: XREFtext.

   More sophisticated user interaction mechanisms can be obtained using
the ui* family of functions, *note UI Elements::.


File: octave.info,  Node: Test Plotting Functions,  Prev: Interacting with Plots,  Up: High-Level Plotting

15.2.11 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 ()
 -- : sombrero (N)
 -- : Z = sombrero (...)
 -- : [X, Y, Z] = sombrero (...)
     Plot the familiar 3-D sombrero function.

     The function plotted is

          z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2))

     Called without a return argument, ‘sombrero’ plots the surface of
     the above function over the meshgrid [-8,8] using ‘surf’.

     If N is a scalar the plot is made with N grid lines.  The default
     value for N is 41.

     When called with output arguments, return the data for the function
     evaluated over the meshgrid.  This can subsequently be plotted with
     ‘surf (X, Y, Z)’.

     See also: *note peaks: XREFpeaks, *note meshgrid: XREFmeshgrid,
     *note mesh: XREFmesh, *note surf: XREFsurf.

 -- : peaks ()
 -- : peaks (N)
 -- : peaks (X, Y)
 -- : Z = peaks (...)
 -- : [X, Y, Z] = peaks (...)
     Plot a function with lots of local maxima and minima.

     The function has the form

     f(x,y) = 3*(1-x)^2*exp(-x^2 - (y+1)^2) ...
              - 10*(x/5 - x^3 - y^5)*exp(-x^2-y^2) ...
              - 1/3*exp(-(x+1)^2 - y^2)

     Called without a return argument, ‘peaks’ plots the surface of the
     above function using ‘surf’.

     If N is a scalar, ‘peaks’ plots the value of the above function on
     an N-by-N mesh over the range [-3,3].  The default value for N is
     49.

     If N is a vector, then it represents the grid values over which to
     calculate the function.  If X and Y are specified then the function
     value is calculated over the specified grid of vertices.

     When called with output arguments, return the data for the function
     evaluated over the meshgrid.  This can subsequently be plotted with
     ‘surf (X, Y, Z)’.

     See also: *note sombrero: XREFsombrero, *note meshgrid:
     XREFmeshgrid, *note mesh: XREFmesh, *note surf: XREFsurf.


File: octave.info,  Node: Graphics Data Structures,  Next: Advanced Plotting,  Prev: High-Level Plotting,  Up: Plotting

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

* Menu:

* Introduction to Graphics Structures::
* Graphics Objects::
* Graphics Object Properties::
* Searching Properties::
* Managing Default Properties::


File: octave.info,  Node: Introduction to Graphics Structures,  Next: Graphics Objects,  Up: Graphics Data Structures

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

The graphics functions use pointers, which are of class graphics_handle,
in order to address the data structures which control visual display.  A
graphics handle may point to any one of a number of different base
object types and these objects are the graphics data structures
themselves.  The primitive graphic object types are: ‘figure’, ‘axes’,
‘line’, ‘text’, ‘patch’, ‘surface’, ‘text’, ‘image’, and ‘light’.

   Each of these objects has a function by the same name, and, each of
these functions returns a graphics handle pointing to an object of the
corresponding type.  In addition there are several functions which
operate on properties of the graphics objects and which also return
handles: 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 to a complex data structure as documented in *note
Data Sources: XREFdatasources.

   The graphics objects are arranged in a hierarchy:

   1.  The root object is returned by ‘groot’ (historically, equivalent
to the handle 0).  In other words, ‘get (groot)’ returns the properties
of the root object.

   2.  Below the root are ‘figure’ objects.

   3.  Below the ‘figure’ objects are ‘axes’ or ‘hggroup’ objects.

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

   Graphics handles may be distinguished from function handles (*note
Function Handles::) by means of the function ‘ishghandle’.  ‘ishghandle’
returns true if its argument is a handle of a graphics object.  In
addition, a figure or axes object may be tested using ‘isfigure’ or
‘isaxes’ respectively.  To test for a specific type of graphics handle,
such as a patch or line object, use ‘isgraphics’.  The more specific
test functions return true only if the argument is both a graphics
handle and of the correct type (figure, axes, specified object type).

   The ‘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:

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

   The properties of the root figure may be displayed by: ‘get (groot,
"")’.

   The uses of ‘get’ and ‘set’ are further explained in *note get:
XREFget, *note set: XREFset.

 -- : RES = isprop (OBJ, "PROP")
     Return true if PROP is a property of the object OBJ.

     OBJ may also be an array of objects in which case RES will be a
     logical array indicating whether each handle has the property PROP.

     For plotting, OBJ is a handle to a graphics object.  Otherwise, OBJ
     should be an instance of a class.

     See also: *note get: XREFget, *note set: XREFset, *note ismethod:
     XREFismethod, *note isobject: XREFisobject.


File: octave.info,  Node: Graphics Objects,  Next: Graphics Object Properties,  Prev: Introduction to Graphics Structures,  Up: Graphics Data Structures

15.3.2 Graphics Objects
-----------------------

The hierarchy of graphics objects was explained above.  *Note
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.  Use ‘groot’ to obtain the handle of the root graphics
     object.

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.

   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 a Cartesian 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.

     Called with a single axes handle argument HAX, the function makes
     HAX the current axes (as returned by ‘gca’).  It also makes the
     figure which contains HAX the current figure (as returned by
     ‘gcf’).  Finally, it restacks the parent object’s ‘children’
     property so that the axes HAX appears before all other axes handles
     in the list.  This causes HAX to be displayed on top of any other
     axes objects (Z-order stacking).  In addition it restacks any
     legend or colorbar objects associated with HAX so that they are
     also visible.

     Programming Note: The full list of properties is documented at
     *note Axes Properties: Axes Properties.

     See also: *note gca: XREFgca, *note set: XREFset, *note 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.

     Programming Note: The full list of properties is documented at
     *note Line Properties: Line Properties.

     See also: *note image: XREFimage, *note patch: XREFpatch, *note
     rectangle: XREFrectangle, *note surface: XREFsurface, *note 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.

     Programming Note: The full list of properties is documented at
     *note Patch Properties: Patch Properties.  Useful patch properties
     include: "cdata", "edgecolor", "facecolor", "faces", and
     "facevertexcdata".

     See also: *note fill: XREFfill, *note get: XREFget, *note 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.

     Programming Note: The full list of properties is documented at
     *note Surface Properties: Surface Properties.

     See also: *note surf: XREFsurf, *note mesh: XREFmesh, *note patch:
     XREFpatch, *note 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.

     Programming Note: The full list of properties is documented at
     *note Light Properties: Light Properties.

     See also: *note lighting: XREFlighting, *note material:
     XREFmaterial, *note patch: XREFpatch, *note 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 ‘ishghandle’, ‘isgraphics’,
‘isaxes’, and ‘isfigure’.

 -- : ishghandle (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: *note isgraphics: XREFisgraphics, *note isaxes:
     XREFisaxes, *note isfigure: XREFisfigure, *note ishandle:
     XREFishandle.

 -- : isgraphics (H)
 -- : isgraphics (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
     ‘ishghandle’.

     See also: *note ishghandle: XREFishghandle, *note ishandle:
     XREFishandle, *note isaxes: XREFisaxes, *note isfigure:
     XREFisfigure.

 -- : ishandle (H)
     Return true if H is a handle to a graphics or Java object 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 handles to
     graphics or Java objects and false where they are not.

     Programming Note: It is often more useful to test for a specific
     object type.  To determine if a handle belongs to a graphics object
     use ‘ishghandle’ or ‘isgraphics’.  To determine if a handle belongs
     to a Java object use ‘isjava’.

     See also: *note ishghandle: XREFishghandle, *note isgraphics:
     XREFisgraphics, *note isjava: XREFisjava.

 -- : 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: *note isfigure: XREFisfigure, *note ishghandle:
     XREFishghandle, *note isgraphics: XREFisgraphics.

 -- : 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: *note isaxes: XREFisaxes, *note ishghandle:
     XREFishghandle, *note isgraphics: XREFisgraphics.

   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 = groot ()
     Return a handle to the root graphics object.

     The root graphics object is the ultimate parent of all graphics
     objects.

     In addition, the root object contains information about the
     graphics system as a whole such as the ‘ScreenSize’.  Use
     ‘get (groot)’ to find out what information is available.

     Defaults for the graphic system as a whole are specified by setting
     properties of the root graphics object that begin with "Default".
     For example, to set the default font for all text objects to
     FreeSans use

          set (groot, "DefaultTextFontName", "FreeSans")

     Default properties can be deleted by using ‘set’ with the special
     property value of "remove".  To undo the default font assignment
     above use

          set (groot, "DefaultTextFontName", "remove")

     Programming Note: The root graphics object is identified by the
     special handle value of 0.  At some point this unique value may
     change, but code can be made resistant to future changes by using
     ‘groot’ which is guaranteed to always return the root graphics
     object.

     See also: *note gcf: XREFgcf, *note gca: XREFgca, *note get:
     XREFget, *note set: XREFset.

 -- : 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 (groot, "currentfigure");

     See also: *note gca: XREFgca, *note gco: XREFgco, *note gcbf:
     XREFgcbf, *note gcbo: XREFgcbo, *note get: XREFget, *note 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");

     See also: *note gcf: XREFgcf, *note gco: XREFgco, *note gcbf:
     XREFgcbf, *note gcbo: XREFgcbo, *note get: XREFget, *note 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.

     See also: *note gcbo: XREFgcbo, *note gca: XREFgca, *note gcf:
     XREFgcf, *note gcbf: XREFgcbf, *note get: XREFget, *note set:
     XREFset.

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

     get (groot)
         ⇒ 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: *note 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: *note 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: *note findobj: XREFfindobj, *note findall: XREFfindall,
     *note 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: *note findall: XREFfindall, *note findobj: XREFfindobj,
     *note get: XREFget, *note set: XREFset.

 -- : findfigs ()
     Find all visible figures that are currently off the screen and move
     them onto the screen.

     See also: *note allchild: XREFallchild, *note figure: XREFfigure,
     *note get: XREFget, *note 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".

     See also: *note struct2hdl: XREFstruct2hdl, *note hgsave:
     XREFhgsave, *note 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.

     See also: *note hdl2struct: XREFhdl2struct, *note hgload:
     XREFhgload, *note 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)’.

     See also: *note struct2hdl: XREFstruct2hdl, *note hdl2struct:
     XREFhdl2struct, *note findobj: XREFfindobj.


File: octave.info,  Node: Graphics Object Properties,  Next: Searching Properties,  Prev: Graphics Objects,  Up: Graphics Data Structures

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

* Menu:

* Root Figure Properties::
* Figure Properties::
* Axes Properties::
* Line Properties::
* Text Properties::
* Image Properties::
* Patch Properties::
* Surface Properties::
* Light Properties::
* Uimenu Properties::
* Uibuttongroup Properties::
* Uicontextmenu Properties::
* Uipanel Properties::
* Uicontrol Properties::
* Uitoolbar Properties::
* Uipushtool Properties::
* Uitoggletool Properties::

In this Section the graphics object properties are discussed in detail,
starting with the root figure properties and continuing through the
objects hierarchy.  The documentation about a specific graphics object
can be displayed using ‘doc’ function, e.g., ‘doc ("axes properties")’
will show *note Axes Properties::.

   The allowed values for radio (string) properties can be retrieved
programmatically or displayed using the one or two arguments call to
‘set’ function.  *Note set: XREFset.

   In the following documentation, default values are enclosed in { }.


File: octave.info,  Node: Root Figure Properties,  Next: Figure Properties,  Up: Graphics Object Properties

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

The ‘root figure’ properties are:

‘beingdeleted’: {"off"} | "on"
     ‘beingdeleted’ is unused.

‘busyaction’: "cancel" | {"queue"}
     ‘busyaction’ is unused.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘callbackobject’ (read-only): graphics handle, def. ‘[](0x0)’
     Graphics handle of the current object whose callback is executing.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the root’s children.

‘clipping’: "off" | {"on"}
     ‘clipping’ is unused.

‘commandwindowsize’ (read-only): def. ‘[0 0]’

‘createfcn’: string | function handle, def. ‘[](0x0)’
     ‘createfcn’ is unused.

‘currentfigure’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the current figure.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     ‘deletefcn’ is unused.

‘fixedwidthfontname’: string, def. "Courier"

‘handlevisibility’: "callback" | "off" | {"on"}
     ‘handlevisibility’ is unused.

‘hittest’: "off" | {"on"}
     ‘hittest’ is unused.

‘interruptible’: "off" | {"on"}
     ‘interruptible’ is unused.

‘monitorpositions’ (read-only):
     ‘monitorpositions’ is unused.

‘parent’: graphics handle, def. ‘[](0x0)’
     Root figure has no parent graphics object.  ‘parent’ is always
     empty.

‘pickableparts’: "all" | "none" | {"visible"}
     ‘pickableparts’ is unused.

‘pointerlocation’: two-element vector, def. ‘[0 0]’
     ‘pointerlocation’ is unused.

‘pointerwindow’ (read-only): graphics handle, def. ‘0’
     ‘pointerwindow’ is unused.

‘screendepth’ (read-only): double

‘screenpixelsperinch’ (read-only): double

‘screensize’ (read-only): four-element vector

‘selected’: {"off"} | "on"
     ‘selected’ is unused.

‘selectionhighlight’: "off" | {"on"}
     ‘selectionhighlight’ is unused.

‘showhiddenhandles’: {"off"} | "on"
     If ‘showhiddenhandles’ is "on", all graphics objects handles are
     visible in their parents’ children list, regardless of the value of
     their ‘handlevisibility’ property.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "root"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     ‘uicontextmenu’ is unused.

‘units’: "centimeters" | "inches" | "normalized" | {"pixels"} | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     ‘visible’ is unused.


File: octave.info,  Node: Figure Properties,  Next: Axes Properties,  Prev: Root Figure Properties,  Up: Graphics Object Properties

15.3.3.2 Figure Properties
..........................

The ‘figure’ properties are:

‘alphamap’: def. 64-by-1 double
     Transparency is not yet implemented for figure objects.  ‘alphamap’
     is unused.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the figure’s children.

‘clipping’: "off" | {"on"}
     ‘clipping’ is unused.

‘closerequestfcn’: string | function handle, def. "closereq"
     Function that is executed when a figure is deleted.  *Note closereq
     function: XREFclosereq.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘color’: colorspec, def. ‘[1 1 1]’
     Color of the figure background.  *Note colorspec: Colors.

‘colormap’: N-by-3 matrix, def. 64-by-3 double
     A matrix containing the RGB color map for the current axes.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after figure has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultfigurecreatefcn", 'disp ("figure
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘currentaxes’: graphics handle, def. ‘[](0x0)’
     Handle to the graphics object of the current axes.

‘currentcharacter’ (read-only): def. ""
     ‘currentcharacter’ is unused.

‘currentobject’ (read-only): graphics handle, def. ‘[](0x0)’

‘currentpoint’ (read-only): two-element vector, def. ‘[0; 0]’
     A 1-by-2 matrix which holds the coordinates of the point over which
     the mouse pointer was when a mouse event occurred.  The X and Y
     coordinates are in units defined by the figure’s ‘units’ property
     and their origin is the lower left corner of the plotting area.

     Events which set ‘currentpoint’ are
     A mouse button was pressed
          always
     A mouse button was released
          only if the figure’s callback ‘windowbuttonupfcn’ is defined
     The pointer was moved while pressing the mouse button (drag)
          only if the figure’s callback ‘windowbuttonmotionfcn’ is
          defined

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before figure is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘dockcontrols’: {"off"} | "on"
     ‘dockcontrols’ is unused.

‘filename’: string, def. ""
     The filename used when saving the plot figure.

‘graphicssmoothing’: "off" | {"on"}
     Use smoothing techniques to reduce the appearance of jagged lines.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the figure’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether figure processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFfigurepickableparts.

‘integerhandle’: "off" | {"on"}
     Assign the next lowest unused integer as the Figure number.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘inverthardcopy’: "off" | {"on"}
     Replace the figure and axes background color with white when
     printing.

‘keypressfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed when a keystroke event happens while the
     figure has focus.  The actual key that was pressed can be retrieved
     using the second argument ’evt’ of the function.  For information
     on how to write graphics listener functions see *note
     Callbacks section: Callbacks.

‘keyreleasefcn’: string | function handle, def. ‘[](0x0)’
     With ‘keypressfcn’, the keyboard callback functions.  These
     callback functions are 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 an 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.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘menubar’: {"figure"} | "none"
     Control the display of the figure menu bar at the top of the
     figure.

‘name’: string, def. ""
     Name to be displayed in the figure title bar.  The name is
     displayed to the right of any title determined by the ‘numbertitle’
     property.

‘nextplot’: {"add"} | "new" | "replace" | "replacechildren"
     ‘nextplot’ is used by high level plotting functions to decide what
     to do with axes already present in the figure.  *Note
     newplot function: XREFnewplot.

‘numbertitle’: "off" | {"on"}
     Display "Figure" followed by the numerical figure handle value in
     the figure title bar.

‘outerposition’: four-element vector, def. ‘[-1 -1 -1 -1]’
     Specify the position and size of the figure including the top
     menubar and the bottom status bar.  The four elements of the vector
     are the coordinates of the lower left corner and width and height
     of the figure.  *Note units property: XREFfigureunits.

‘paperorientation’: "landscape" | {"portrait"}
     The value for the ‘papersize’, and ‘paperposition’ properties
     depends upon ‘paperorientation’.  The horizontal and vertical
     values for ‘papersize’ and ‘paperposition’ reverse order when
     ‘paperorientation’ is switched between ‘"portrait"’ and
     ‘"landscape"’.

‘paperposition’: four-element vector, def. ‘[0.25000 2.50000 8.00000 6.00000]’
     Vector ‘[left bottom width height]’ defining the position and size
     of the figure (in ‘paperunits’ units) on the printed page.  The
     position ‘[left bottom]’ defines the lower left corner of the
     figure on the page, and the size is defined by ‘[width height]’.
     For output formats not implicitly rendered on paper, ‘width’ and
     ‘height’ define the size of the image and the position information
     is ignored.  Setting ‘paperposition’ also forces the
     ‘paperpositionmode’ property to be set to "manual".

‘paperpositionmode’: "auto" | {"manual"}
     If ‘paperpositionmode’ is set to "auto", the ‘paperposition’
     property is automatically computed: the printed figure will have
     the same size as the on-screen figure and will be centered on the
     output page.  Setting the ‘paperpositionmode’ to ‘"auto"’ does not
     modify the value of the ‘paperposition’ property.

‘papersize’: two-element vector, def. ‘[8.5000 11.0000]’
     Vector ‘[width height]’ defining the size of the paper for
     printing.  Setting the ‘papersize’ property to a value, not
     associated with one of the defined ‘papertypes’ and consistent with
     the setting for ‘paperorientation’, forces the ‘papertype’ property
     to the value "<custom>".  If ‘papersize’ is set to a value
     associated with a supported ‘papertype’ and consistent with the
     ‘paperorientation’, the ‘papertype’ value is modified to the
     associated value.

‘papertype’: "<custom>" | "a" | "a0" | "a1" | "a2" | "a3" | "a4" | "a5" | "arch-a" | "arch-b" | "arch-c" | "arch-d" | "arch-e" | "b" | "b0" | "b1" | "b2" | "b3" | "b4" | "b5" | "c" | "d" | "e" | "tabloid" | "uslegal" | {"usletter"}
     Name of the paper used for printed output.  Setting ‘papertype’
     also changes ‘papersize’, while maintaining consistency with the
     ‘paperorientation’ property.

‘paperunits’: "centimeters" | {"inches"} | "normalized" | "points"
     The unit used to compute the ‘paperposition’ property.  For
     ‘paperunits’ set to ‘"pixels"’, the conversion between physical
     units (ex: ‘"inches"’) and ‘"pixels"’ is dependent on the
     ‘screenpixelsperinch’ property of the root object.

‘parent’: graphics handle, def. ‘0’
     Handle of the parent graphics object.

‘pickableparts’ (read-only): "all" | "none" | {"visible"}
     ‘pickableparts’ is unused.

‘pointer’: {"arrow"} | "botl" | "botr" | "bottom" | "circle" | "cross" | "crosshair" | "custom" | "fleur" | "fullcrosshair" | "hand" | "ibeam" | "left" | "right" | "top" | "topl" | "topr" | "watch"
     ‘pointer’ is unused.

‘pointershapecdata’: def. 16-by-16 double
     ‘pointershapecdata’ is unused.

‘pointershapehotspot’: def. ‘[0 0]’
     ‘pointershapehotspot’ is unused.

‘position’: four-element vector, def. ‘[300 200 560 420]’
     Specify the position and size of the figure canvas.  The four
     elements of the vector are the coordinates of the lower left corner
     and width and height of the figure.  *Note units property:
     XREFfigureunits.

‘renderer’: {"opengl"} | "painters"
     ‘renderer’ is unused.

‘renderermode’: {"auto"} | "manual"
     ‘renderermode’ is unused.

‘resize’: "off" | {"on"}
     ‘resize’ is unused.

‘resizefcn’: string | function handle, def. ‘[](0x0)’
     ‘resizefcn’ is deprecated.  Use ‘sizechangedfcn’ instead.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘selectiontype’: "alt" | "extend" | {"normal"} | "open"

‘sizechangedfcn’: string | function handle, def. ‘[](0x0)’
     Callback triggered when the figure window size is changed.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘toolbar’: {"auto"} | "figure" | "none"
     Control the display of the toolbar (along the bottom of the
     menubar) and the status bar.  When set to "auto", the display is
     based on the value of the ‘menubar’ property.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "figure"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this figure object.

‘units’: "centimeters" | "characters" | "inches" | "normalized" | {"pixels"} | "points"
     The unit used to compute the ‘position’ and ‘outerposition’
     properties.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the figure is not rendered on screen.

‘windowbuttondownfcn’: string | function handle, def. ‘[](0x0)’
     *Note windowbuttonupfcn property: XREFfigurewindowbuttonupfcn.

‘windowbuttonmotionfcn’: string | function handle, def. ‘[](0x0)’
     *Note windowbuttonupfcn property: XREFfigurewindowbuttonupfcn.

‘windowbuttonupfcn’: string | function handle, def. ‘[](0x0)’
     With ‘windowbuttondownfcn’ and ‘windowbuttonmotionfcn’, the mouse
     callback functions.  These callback functions are called when a
     mouse button is pressed, dragged, or released respectively.  When
     these callback functions are executed, the ‘currentpoint’ property
     holds the current coordinates of the cursor.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘windowkeypressfcn’: string | function handle, def. ‘[](0x0)’
     Function that is executed when a key is pressed and the figure has
     focus.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘windowkeyreleasefcn’: string | function handle, def. ‘[](0x0)’
     Function that is executed when a key is released and the figure has
     focus.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘windowscrollwheelfcn’: string | function handle, def. ‘[](0x0)’
     ‘windowscrollwheelfcn’ is unused.

‘windowstyle’: "docked" | "modal" | {"normal"}
     The window style of a figure.  One of the following values:
     ‘normal’
          Set the window style as non modal.
     ‘modal’
          Set the window as modal so that it will stay on top of all
          normal figures.
     ‘docked’
          Setting the window style as docked currently does not dock the
          window.

     Changing modes of a visible figure may cause the figure to close
     and reopen.


File: octave.info,  Node: Axes Properties,  Next: Line Properties,  Prev: Figure Properties,  Up: Graphics Object Properties

15.3.3.3 Axes Properties
........................

The ‘axes’ properties are:

‘activepositionproperty’: {"outerposition"} | "position"
     Specify which of "position" or "outerposition" properties takes
     precedence when axes annotations extent changes.  *Note
     position property: XREFaxesposition, and *note
     outerposition property: XREFaxesposition.

‘alim’: def. ‘[0 1]’
     Transparency is not yet implemented for axes objects.  ‘alim’ is
     unused.

‘alimmode’: {"auto"} | "manual"

‘ambientlightcolor’: def. ‘[1 1 1]’
     ‘ambientlightcolor’ is unused.

‘beingdeleted’: {"off"} | "on"

‘box’: {"off"} | "on"
     Control whether the axes has a surrounding box.

‘boxstyle’: {"back"} | "full"
     For 3-D axes, control whether the "full" box is drawn or only the 3
     "back" axes

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘cameraposition’: three-element vector, def. ‘[0.50000 0.50000 9.16025]’

‘camerapositionmode’: {"auto"} | "manual"

‘cameratarget’: three-element vector, def. ‘[0.50000 0.50000 0.50000]’

‘cameratargetmode’: {"auto"} | "manual"

‘cameraupvector’: three-element vector, def. ‘[-0 1 0]’

‘cameraupvectormode’: {"auto"} | "manual"

‘cameraviewangle’: scalar, def. ‘6.6086’

‘cameraviewanglemode’: {"auto"} | "manual"

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the axes’s children.

‘clim’: two-element vector, def. ‘[0 1]’
     Define the limits for the color axis of image children.  Setting
     ‘clim’ also forces the ‘climmode’ property to be set to "manual".
     *Note pcolor function: XREFpcolor.

‘climmode’: {"auto"} | "manual"

‘clipping’: "off" | {"on"}
     ‘clipping’ is unused.

‘clippingstyle’: {"3dbox"} | "rectangle"
     ‘clippingstyle’ is unused.

‘color’: colorspec, def. ‘[1 1 1]’
     Color of the axes background.  *Note colorspec: Colors.

‘colormap’: def. 64-by-3 double

‘colororder’: N-by-3 RGB matrix, def. 7-by-3 double
     RGB values used by plot function for automatic line coloring.

‘colororderindex’: def. ‘1’
     ‘colororderindex’ is unused.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after axes has been created.
     Function is set by using default property on root object, e.g.,
     ‘set (groot, "defaultaxescreatefcn", 'disp ("axes created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘currentpoint’: 2-by-3 matrix, def. 2-by-3 double
     Matrix ‘[xf, yf, zf; xb, yb, zb]’ which holds the coordinates (in
     axes data units) 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 pointer coordinates at the time
     the mouse button was pressed.  For 3-D plots, the first row of the
     returned matrix specifies the point nearest to the current camera
     position and the second row the furthest point.  The two points
     forms a line which is perpendicular to the screen.

‘dataaspectratio’: three-element vector, def. ‘[1 1 1]’
     Specify 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 x-axis to be the same as the length of
     2 units on the y-axis.  *Note daspect function: XREFdaspect.
     Setting ‘dataaspectratio’ also forces the ‘dataaspectratiomode’
     property to be set to "manual".

‘dataaspectratiomode’: {"auto"} | "manual"

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before axes is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFaxesfontunits.

‘fontsmoothing’: "off" | {"on"}
     ‘fontsmoothing’ is unused.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.

‘gridalpha’: def. ‘0.15000’
     Transparency is not yet implemented for axes objects.  ‘gridalpha’
     is unused.

‘gridalphamode’: {"auto"} | "manual"
     ‘gridalphamode’ is unused.

‘gridcolor’: def. ‘[0.15000 0.15000 0.15000]’
     ‘gridcolor’ is unused.

‘gridcolormode’: {"auto"} | "manual"
     ‘gridcolormode’ is unused.

‘gridlinestyle’: {"-"} | "–" | "-." | ":" | "none"

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the axes’s handle is not visible in
     its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether axes processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFaxespickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘labelfontsizemultiplier’: def. ‘1.1000’
     Ratio between the x/y/zlabel fontsize and the tick label fontsize

‘layer’: {"bottom"} | "top"
     Control whether the axes is drawn below child graphics objects
     (ticks, labels, etc. covered by plotted objects) or above.

‘linestyleorder’: def. "-"
     ‘linestyleorder’ is unused.

‘linestyleorderindex’: def. ‘1’
     ‘linestyleorderindex’ is unused.

‘linewidth’: def. ‘0.50000’
     Width of the main axes lines

‘minorgridalpha’: def. ‘0.25000’
     Transparency is not yet implemented for axes objects.
     ‘minorgridalpha’ is unused.

‘minorgridalphamode’: {"auto"} | "manual"
     ‘minorgridalphamode’ is unused.

‘minorgridcolor’: def. ‘[0.10000 0.10000 0.10000]’
     ‘minorgridcolor’ is unused.

‘minorgridcolormode’: {"auto"} | "manual"
     ‘minorgridcolormode’ is unused.

‘minorgridlinestyle’: "-" | "–" | "-." | {":"} | "none"

‘mousewheelzoom’: scalar in the range (0, 1), def. ‘0.50000’
     Fraction of axes limits to zoom for each wheel movement.

‘nextplot’: "add" | {"replace"} | "replacechildren"
     ‘nextplot’ is used by high level plotting functions to decide what
     to do with graphics objects already present in the axes.  *Note
     newplot function: XREFnewplot.  The state of ‘nextplot’ is
     typically controlled using the ‘hold’ function.  *Note
     hold function: XREFhold.

‘outerposition’: four-element vector, def. ‘[0 0 1 1]’
     Specify 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.  *Note position property: XREFaxesposition.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether axes will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the axes or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFaxeshittest.

‘plotboxaspectratio’: def. ‘[1 1 1]’
     *Note pbaspect function: XREFpbaspect.  Setting
     ‘plotboxaspectratio’ also forces the ‘plotboxaspectratiomode’
     property to be set to "manual".

‘plotboxaspectratiomode’: {"auto"} | "manual"

‘position’: four-element vector, def. ‘[0.13000 0.11000 0.77500 0.81500]’
     Specify 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.  *Note outerposition property: XREFaxesouterposition.

‘projection’: {"orthographic"} | "perspective"
     ‘projection’ is unused.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘sortmethod’: "childorder" | {"depth"}
     ‘sortmethod’ is unused.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tickdir’: {"in"} | "out"
     Control whether axes tick marks project "in" to the plot box or
     "out".  Setting ‘tickdir’ also forces the ‘tickdirmode’ property to
     be set to "manual".

‘tickdirmode’: {"auto"} | "manual"

‘ticklabelinterpreter’: "latex" | "none" | {"tex"}
     Control the way x/y/zticklabel properties are interpreted.  *Note
     Use of the interpreter property: XREFinterpreterusage.

‘ticklength’: two-element vector, def. ‘[0.010000 0.025000]’
     Two-element vector ‘[2Dlen 3Dlen]’ specifying the length of the
     tickmarks relative to the longest visible axis.

‘tightinset’ (read-only): four-element vector, def. ‘[0.042857 0.038106 0.000000 0.023810]’
     Size of the ‘[left bottom right top]’ margins around the axes that
     enclose labels and title annotations.

‘title’: graphics handle
     Graphics handle of the title text object.

‘titlefontsizemultiplier’: positive scalar, def. ‘1.1000’
     Ratio between the title fontsize and the tick label fontsize

‘titlefontweight’: {"bold"} | "normal"
     Control variant of base font used for the axes title.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "axes"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this axes object.

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"
     Units used to interpret the "position", "outerposition", and
     "tightinset" properties.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘view’: two-element vector, def. ‘[0 90]’
     Two-element vector ‘[azimuth elevation]’ specifying the viewpoint
     for three-dimensional plots

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the axes is not rendered on screen.

‘xaxislocation’: {"bottom"} | "origin" | "top" | "zero"
     Control the x axis location.

‘xcolor’: {colorspec} | "none", def. ‘[0.15000 0.15000 0.15000]’
     Color of the x-axis.  *Note colorspec: Colors.  Setting ‘xcolor’
     also forces the ‘xcolormode’ property to be set to "manual".

‘xcolormode’: {"auto"} | "manual"

‘xdir’: {"normal"} | "reverse"
     Direction of the x axis: "normal" is left to right.

‘xgrid’: {"off"} | "on"
     Control whether major x grid lines are displayed.

‘xlabel’: graphics handle
     Graphics handle of the x label text object.

‘xlim’: two-element vector, def. ‘[0 1]’
     Two-element vector ‘[xmin xmax]’ specifying the limits for the
     x-axis.  Setting ‘xlim’ also forces the ‘xlimmode’ property to be
     set to "manual".  *Note xlim function: XREFxlim.

‘xlimmode’: {"auto"} | "manual"

‘xminorgrid’: {"off"} | "on"
     Control whether minor x grid lines are displayed.

‘xminortick’: {"off"} | "on"

‘xscale’: {"linear"} | "log"

‘xtick’: vector
     Position of x tick marks.  Setting ‘xtick’ also forces the
     ‘xtickmode’ property to be set to "manual".

‘xticklabel’: string | cell array of strings, def. 1-by-6 cell
     Labels of x tick marks.  Setting ‘xticklabel’ also forces the
     ‘xticklabelmode’ property to be set to "manual".

‘xticklabelmode’: {"auto"} | "manual"

‘xticklabelrotation’: def. ‘0’
     ‘xticklabelrotation’ is unused.

‘xtickmode’: {"auto"} | "manual"

‘yaxislocation’: {"left"} | "origin" | "right" | "zero"
     Control the y-axis location.

‘ycolor’: {colorspec} | "none", def. ‘[0.15000 0.15000 0.15000]’
     Color of the y-axis.  *Note colorspec: Colors.

‘ycolormode’: {"auto"} | "manual"

‘ydir’: {"normal"} | "reverse"
     Direction of the y-axis: "normal" is bottom to top.

‘ygrid’: {"off"} | "on"
     Control whether major y grid lines are displayed.

‘ylabel’: graphics handle
     Graphics handle of the y label text object.

‘ylim’: two-element vector, def. ‘[0 1]’
     Two-element vector ‘[ymin ymax]’ specifying the limits for the
     y-axis.  Setting ‘ylim’ also forces the ‘ylimmode’ property to be
     set to "manual".  *Note ylim function: XREFylim.

‘ylimmode’: {"auto"} | "manual"

‘yminorgrid’: {"off"} | "on"
     Control whether minor y grid lines are displayed.

‘yminortick’: {"off"} | "on"

‘yscale’: {"linear"} | "log"

‘ytick’: vector
     Position of y tick marks.  Setting ‘ytick’ also forces the
     ‘ytickmode’ property to be set to "manual".

‘yticklabel’: string | cell array of strings, def. 1-by-6 cell
     Labels of y tick marks.  Setting ‘yticklabel’ also forces the
     ‘yticklabelmode’ property to be set to "manual".

‘yticklabelmode’: {"auto"} | "manual"

‘yticklabelrotation’: def. ‘0’
     ‘yticklabelrotation’ is unused.

‘ytickmode’: {"auto"} | "manual"

‘zcolor’: {colorspec} | "none", def. ‘[0.15000 0.15000 0.15000]’
     Color of the z-axis.  *Note colorspec: Colors.

‘zcolormode’: {"auto"} | "manual"

‘zdir’: {"normal"} | "reverse"

‘zgrid’: {"off"} | "on"
     Control whether major z grid lines are displayed.

‘zlabel’: graphics handle
     Graphics handle of the z label text object.

‘zlim’: two-element vector, def. ‘[0 1]’
     Two-element vector ‘[zmin zmaz]’ specifying the limits for the
     z-axis.  Setting ‘zlim’ also forces the ‘zlimmode’ property to be
     set to "manual".  *Note zlim function: XREFzlim.

‘zlimmode’: {"auto"} | "manual"

‘zminorgrid’: {"off"} | "on"
     Control whether minor z grid lines are displayed.

‘zminortick’: {"off"} | "on"

‘zscale’: {"linear"} | "log"

‘ztick’: vector
     Position of z tick marks.  Setting ‘ztick’ also forces the
     ‘ztickmode’ property to be set to "manual".

‘zticklabel’: string | cell array of strings, def. 1-by-6 cell
     Labels of z tick marks.  Setting ‘zticklabel’ also forces the
     ‘zticklabelmode’ property to be set to "manual".

‘zticklabelmode’: {"auto"} | "manual"

‘zticklabelrotation’: def. ‘0’
     ‘zticklabelrotation’ is unused.

‘ztickmode’: {"auto"} | "manual"


File: octave.info,  Node: Line Properties,  Next: Text Properties,  Prev: Axes Properties,  Up: Graphics Object Properties

15.3.3.4 Line Properties
........................

The ‘line’ properties are:

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the line is clipped in its parent axes
     limits.

‘color’: colorspec, def. ‘[0 0 0]’
     Color of the line object.  *Note colorspec: Colors.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after line has been created.
     Function is set by using default property on root object, e.g.,
     ‘set (groot, "defaultlinecreatefcn", 'disp ("line created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before line is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘displayname’: string | cell array of strings, def. ""
     Text for the legend entry corresponding to this line.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the line’s handle is not visible in
     its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether line processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFlinepickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘linejoin’: "chamfer" | "miter" | {"round"}
     Control the shape of the junction of line segments.  This property
     currently only affects the printed output.

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"
     *Note Line Styles::.

‘linewidth’: def. ‘0.50000’
     Width of the line object measured in points.

‘marker’: "*" | "+" | "." | "<" | ">" | "^" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x"
     Shape of the marker for each data point.  *Note Marker Styles::.

‘markeredgecolor’: {"auto"} | "none"
     Color of the edge of the markers.  When set to "auto", the marker
     edges have the same color as the line.  If set to "none", no marker
     edges are displayed.  This property can also be set to any color.
     *Note colorspec: Colors.

‘markerfacecolor’: "auto" | {"none"}
     Color of the face of the markers.  When set to "auto", the marker
     faces have the same color as the line.  If set to "none", the
     marker faces are not displayed.  This property can also be set to
     any color.  *Note colorspec: Colors.

‘markersize’: scalar, def. ‘6’
     Size of the markers measured in points.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether line will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the line or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFlinehittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "line"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this line object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the line is not rendered on screen.

‘xdata’: vector, def. ‘[0 1]’
     Vector of x data to be plotted.

‘xdatasource’: string, def. ""
     Name of a vector in the current base workspace to use as x data.

‘ydata’: vector, def. ‘[0 1]’
     Vector of y data to be plotted.

‘ydatasource’: string, def. ""
     Name of a vector in the current base workspace to use as y data.

‘zdata’: vector, def. ‘[](0x0)’
     Vector of z data to be plotted.

‘zdatasource’: string, def. ""
     Name of a vector in the current base workspace to use as z data.


File: octave.info,  Node: Text Properties,  Next: Image Properties,  Prev: Line Properties,  Up: Graphics Object Properties

15.3.3.5 Text Properties
........................

The ‘text’ properties are:

‘backgroundcolor’: colorspec, def. "none"
     Color of the background area.  *Note colorspec: Colors.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the text is clipped in its parent axes
     limits.

‘color’: colorspec, def. ‘[0 0 0]’
     Color of the text.  *Note colorspec: Colors.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after text has been created.
     Function is set by using default property on root object, e.g.,
     ‘set (groot, "defaulttextcreatefcn", 'disp ("text created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before text is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘edgecolor’: colorspec, def. "none"
     Color of the outline of the background area.  *Note colorspec:
     Colors.

‘editing’: {"off"} | "on"
     ‘editing’ is unused.

‘extent’ (read-only): four-element vector, def. ‘[0.000000 -0.005843 0.000000 0.032136]’
     Vector ‘[x0 y0 width height]’ indicating the size and location of
     the text string.

‘fontangle’: "italic" | {"normal"} | "oblique"
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFtextfontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | "demi" | "light" | {"normal"}
     Control the variant of the base font used for text rendering.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the text’s handle is not visible in
     its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether text processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFtextpickableparts.

‘horizontalalignment’: "center" | {"left"} | "right"

‘interpreter’: "latex" | "none" | {"tex"}
     Control the way the "string" property is interpreted.  *Note
     Use of the interpreter property: XREFinterpreterusage.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"
     Style of the outline.  *Note Line Styles::.

‘linewidth’: scalar, def. ‘0.50000’
     Width of the outline.

‘margin’: scalar, def. ‘2’
     Margins between the borders of the background area and the texts.
     The value is currently interpreted as pixels, regardless of the
     "fontunits" property.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether text will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the text or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFtexthittest.

‘position’: four-element vector, def. ‘[0 0 0]’
     Vector ‘[X0 Y0 Z0]’ where X0, Y0 and Z0 indicate the position of
     the text anchor as defined by ‘verticalalignment’ and
     ‘horizontalalignment’.

‘rotation’: scalar, def. ‘0’
     The angle of rotation for the displayed text, measured in degrees.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘string’: string, def. ""
     The text object string content.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "text"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this text object.

‘units’: "centimeters" | {"data"} | "inches" | "normalized" | "pixels" | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘verticalalignment’: "baseline" | "bottom" | "cap" | {"middle"} | "top"

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the text is not rendered on screen.


File: octave.info,  Node: Image Properties,  Next: Patch Properties,  Prev: Text Properties,  Up: Graphics Object Properties

15.3.3.6 Image Properties
.........................

The ‘image’ properties are:

‘alphadata’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for image objects.  ‘alphadata’
     is unused.

‘alphadatamapping’: "direct" | {"none"} | "scaled"
     Transparency is not yet implemented for image objects.
     ‘alphadatamapping’ is unused.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘cdata’: matrix, def. 64-by-64 double

‘cdatamapping’: {"direct"} | "scaled"

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the image is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after image has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultimagecreatefcn", 'disp ("image
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before image is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the image’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether image processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFimagepickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether image will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the image or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFimagehittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "image"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this image object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the image is not rendered on screen.

‘xdata’: two-element vector, def. ‘[1 64]’
     Two-element vector ‘[xmin xmax]’ specifying the x coordinates of
     the first and last columns of the image.

     Setting ‘xdata’ to the empty matrix ([]) will restore the default
     value of ‘[1 columns(image)]’.

‘ydata’: two-element vector, def. ‘[1 64]’
     Two-element vector ‘[ymin ymax]’ specifying the y coordinates of
     the first and last rows of the image.

     Setting ‘ydata’ to the empty matrix ([]) will restore the default
     value of ‘[1 rows(image)]’.


File: octave.info,  Node: Patch Properties,  Next: Surface Properties,  Prev: Image Properties,  Up: Graphics Object Properties

15.3.3.7 Patch Properties
.........................

The ‘patch’ properties are:

‘alphadatamapping’: "direct" | "none" | {"scaled"}
     Transparency is not yet implemented for patch objects.
     ‘alphadatamapping’ is unused.

‘ambientstrength’: scalar, def. ‘0.30000’
     Strength of the ambient light.  Value between 0.0 and 1.0

‘backfacelighting’: "lit" | {"reverselit"} | "unlit"
     "lit": The normals are used as is for lighting.  "reverselit": The
     normals are always oriented towards the point of view.  "unlit":
     Faces with normals pointing away from the point of view are unlit.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘cdata’: scalar | matrix, def. ‘[](0x0)’
     Data defining the patch object color.  Patch color can be defined
     for faces or for vertices.

     If ‘cdata’ is a scalar index into the current colormap or a RGB
     triplet, it defines the color of all faces.

     If ‘cdata’ is an N-by-1 vector of indices or an N-by-3 (RGB)
     matrix, it defines the color of each one of the N faces.

     If ‘cdata’ is an N-by-M or an N-by-M-by-3 (RGB) matrix, it defines
     the color at each vertex.

‘cdatamapping’: "direct" | {"scaled"}

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the patch is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after patch has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultpatchcreatefcn", 'disp ("patch
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before patch is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘diffusestrength’: scalar, def. ‘0.60000’
     Strength of the diffuse reflex.  Value between 0.0 (no diffuse
     reflex) and 1.0 (full diffuse reflex).

‘displayname’: def. ""
     Text of the legend entry corresponding to this patch.

‘edgealpha’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for patch objects.  ‘edgealpha’
     is unused.

‘edgecolor’: def. ‘[0 0 0]’

‘edgelighting’: "flat" | "gouraud" | {"none"} | "phong"
     When set to a value other than "none", the edges of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facealpha’: scalar | "flat" | "interp", def. ‘1’
     Transparency level of the faces of the patch object.  Only double
     values are supported at present where a value of 0 means complete
     transparency and a value of 1 means solid faces without
     transparency.  Setting the property to "flat" or "interp" causes
     the faces to not being rendered.  Additionally, the faces are not
     sorted from back to front which might lead to unexpected results
     when rendering layered transparent faces.

‘facecolor’: {colorspec} | "none" | "flat" | "interp", def. ‘[0 0 0]’

‘facelighting’: {"flat"} | "gouraud" | "none" | "phong"
     When set to a value other than "none", the faces of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facenormals’: def. ‘[](0x0)’

‘facenormalsmode’: {"auto"} | "manual"

‘faces’: def. ‘[1 2 3]’

‘facevertexalphadata’: scalar | matrix, def. ‘[](0x0)’
     Transparency is not yet implemented for patch objects.
     ‘facevertexalphadata’ is unused.

‘facevertexcdata’: def. ‘[](0x0)’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the patch’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether patch processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFpatchpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"

‘linewidth’: def. ‘0.50000’

‘marker’: "*" | "+" | "." | "<" | ">" | "^" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x"
     *Note line marker property: XREFlinemarker.

‘markeredgecolor’: {"auto"} | "flat" | "none"
     *Note line markeredgecolor property: XREFlinemarkeredgecolor.

‘markerfacecolor’: "auto" | "flat" | {"none"}
     *Note line markerfacecolor property: XREFlinemarkerfacecolor.

‘markersize’: scalar, def. ‘6’
     *Note line markersize property: XREFlinemarkersize.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether patch will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the patch or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFpatchhittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘specularcolorreflectance’: scalar, def. ‘1’
     Reflectance for specular color.  Value between 0.0 (color of
     underlying face) and 1.0 (color of light source).

‘specularexponent’: scalar, def. ‘10’
     Exponent for the specular reflex.  The lower the value, the more
     the reflex is spread out.

‘specularstrength’: scalar, def. ‘0.90000’
     Strength of the specular reflex.  Value between 0.0 (no specular
     reflex) and 1.0 (full specular reflex).

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "patch"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this patch object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘vertexnormals’: def. ‘[](0x0)’

‘vertexnormalsmode’: {"auto"} | "manual"

‘vertices’: vector | matrix, def. 3-by-2 double

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the patch is not rendered on screen.

‘xdata’: vector | matrix, def. ‘[0; 1; 0]’

‘ydata’: vector | matrix, def. ‘[1; 1; 0]’

‘zdata’: vector | matrix, def. ‘[](0x0)’


File: octave.info,  Node: Surface Properties,  Next: Light Properties,  Prev: Patch Properties,  Up: Graphics Object Properties

15.3.3.8 Surface Properties
...........................

The ‘surface’ properties are:

‘alphadata’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for surface objects.
     ‘alphadata’ is unused.

‘alphadatamapping’: "direct" | "none" | {"scaled"}
     Transparency is not yet implemented for surface objects.
     ‘alphadatamapping’ is unused.

‘ambientstrength’: scalar, def. ‘0.30000’
     Strength of the ambient light.  Value between 0.0 and 1.0

‘backfacelighting’: "lit" | {"reverselit"} | "unlit"
     "lit": The normals are used as is for lighting.  "reverselit": The
     normals are always oriented towards the point of view.  "unlit":
     Faces with normals pointing away from the point of view are unlit.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘cdata’: matrix, def. 3-by-3 double

‘cdatamapping’: "direct" | {"scaled"}

‘cdatasource’: def. ""

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the surface is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after surface has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultsurfacecreatefcn", 'disp ("surface
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before surface is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘diffusestrength’: scalar, def. ‘0.60000’
     Strength of the diffuse reflex.  Value between 0.0 (no diffuse
     reflex) and 1.0 (full diffuse reflex).

‘displayname’: def. ""
     Text for the legend entry corresponding to this surface.

‘edgealpha’: scalar, def. ‘1’
     Transparency is not yet implemented for surface objects.
     ‘edgealpha’ is unused.

‘edgecolor’: def. ‘[0 0 0]’

‘edgelighting’: "flat" | "gouraud" | {"none"} | "phong"
     When set to a value other than "none", the edges of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facealpha’: scalar | "flat" | "interp" | "texturemap", def. ‘1’
     Transparency level of the faces of the surface object.  Only double
     values are supported at present where a value of 0 means complete
     transparency and a value of 1 means solid faces without
     transparency.  Setting the property to "flat", "interp" or
     "texturemap" causes the faces to not being rendered.  Additionally,
     the faces are not sorted from back to front which might lead to
     unexpected results when rendering layered transparent faces.

‘facecolor’: {"flat"} | "interp" | "none" | "texturemap"

‘facelighting’: {"flat"} | "gouraud" | "none" | "phong"
     When set to a value other than "none", the faces of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facenormals’: def. ‘[](0x0)’

‘facenormalsmode’: {"auto"} | "manual"

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the surface’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether surface processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFsurfacepickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"
     *Note Line Styles::.

‘linewidth’: def. ‘0.50000’
     *Note line linewidth property: XREFlinelinewidth.

‘marker’: "*" | "+" | "." | "<" | ">" | "^" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x"
     *Note Marker Styles::.

‘markeredgecolor’: {"auto"} | "flat" | "none"
     *Note line markeredgecolor property: XREFlinemarkeredgecolor.

‘markerfacecolor’: "auto" | "flat" | {"none"}
     *Note line markerfacecolor property: XREFlinemarkerfacecolor.

‘markersize’: scalar, def. ‘6’
     *Note line markersize property: XREFlinemarkersize.

‘meshstyle’: {"both"} | "column" | "row"

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether surface will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the surface
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFsurfacehittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘specularcolorreflectance’: scalar, def. ‘1’
     Reflectance for specular color.  Value between 0.0 (color of
     underlying face) and 1.0 (color of light source).

‘specularexponent’: scalar, def. ‘10’
     Exponent for the specular reflex.  The lower the value, the more
     the reflex is spread out.

‘specularstrength’: scalar, def. ‘0.90000’
     Strength of the specular reflex.  Value between 0.0 (no specular
     reflex) and 1.0 (full specular reflex).

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "surface"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this surface object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘vertexnormals’: def. 3-by-3-by-3 double

‘vertexnormalsmode’: {"auto"} | "manual"

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the surface is not rendered on screen.

‘xdata’: matrix, def. ‘[1 2 3]’

‘xdatasource’: def. ""

‘ydata’: matrix, def. ‘[1; 2; 3]’

‘ydatasource’: def. ""

‘zdata’: matrix, def. 3-by-3 double

‘zdatasource’: def. ""


File: octave.info,  Node: Light Properties,  Next: Uimenu Properties,  Prev: Surface Properties,  Up: Graphics Object Properties

15.3.3.9 Light Properties
.........................

The ‘light’ properties are:

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the light is clipped in its parent axes
     limits.

‘color’: colorspec, def. ‘[1 1 1]’
     Color of the light source.  *Note colorspec: Colors.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after light has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultlightcreatefcn", 'disp ("light
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before light is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the light’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether light processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFlightpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether light will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the light or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFlighthittest.

‘position’: def. ‘[1 0 1]’
     Position of the light source.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘style’: {"infinite"} | "local"
     This string defines whether the light emanates from a light source
     at infinite distance ("infinite") or from a local point source
     ("local").

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "light"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this light object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the light is not rendered on screen.


File: octave.info,  Node: Uimenu Properties,  Next: Uibuttongroup Properties,  Prev: Light Properties,  Up: Graphics Object Properties

15.3.3.10 Uimenu Properties
...........................

The ‘uimenu’ properties are:

‘accelerator’: def. ""

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘callback’: def. ‘[](0x0)’

‘checked’: {"off"} | "on"

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uimenu’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uimenu is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uimenu has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuimenucreatefcn", 'disp ("uimenu
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uimenu is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘enable’: "off" | {"on"}

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uimenu’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uimenu processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuimenupickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘label’: def. ""

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uimenu will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the uimenu
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFuimenuhittest.

‘position’: def. ‘4’

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘separator’: {"off"} | "on"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uimenu"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uimenu object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uimenu is not rendered on screen.


File: octave.info,  Node: Uibuttongroup Properties,  Next: Uicontextmenu Properties,  Prev: Uimenu Properties,  Up: Graphics Object Properties

15.3.3.11 Uibuttongroup Properties
..................................

The ‘uibuttongroup’ properties are:

‘backgroundcolor’: def. ‘[0.93725 0.92157 0.90588]’

‘beingdeleted’: {"off"} | "on"

‘bordertype’: "beveledin" | "beveledout" | {"etchedin"} | "etchedout" | "line" | "none"

‘borderwidth’: def. ‘1’

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uibuttongroup’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uibuttongroup is clipped in its parent
     axes limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uibuttongroup has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuibuttongroupcreatefcn", 'disp
     ("uibuttongroup created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uibuttongroup is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘fontangle’: "italic" | {"normal"} | "oblique"
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFuibuttongroupfontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | "demi" | "light" | {"normal"}
     Control the variant of the base font used for text rendering.

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uibuttongroup’s handle is not
     visible in its parent’s "children" property.

‘highlightcolor’: def. ‘[1 1 1]’

‘hittest’: "off" | {"on"}
     Specify whether uibuttongroup processes mouse events or passes them
     to ancestors of the object.  When enabled, the object may respond
     to mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuibuttongrouppickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uibuttongroup will accept mouse clicks.  By
     default, ‘pickableparts’ is "visible" and only visible parts of the
     uibuttongroup or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuibuttongrouphittest.

‘position’: def. ‘[0 0 1 1]’

‘resizefcn’: def. ‘[](0x0)’

‘selected’: {"off"} | "on"

‘selectedobject’: def. ‘[](0x0)’

‘selectionchangedfcn’: def. ‘[](0x0)’

‘selectionhighlight’: "off" | {"on"}

‘shadowcolor’: def. ‘[0.62483 0.61437 0.60391]’

‘sizechangedfcn’: def. ‘[](0x0)’

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘title’: def. ""

‘titleposition’: "centerbottom" | "centertop" | "leftbottom" | {"lefttop"} | "rightbottom" | "righttop"

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always
     "uibuttongroup"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uibuttongroup object.

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uibuttongroup is not rendered on screen.


File: octave.info,  Node: Uicontextmenu Properties,  Next: Uipanel Properties,  Prev: Uibuttongroup Properties,  Up: Graphics Object Properties

15.3.3.12 Uicontextmenu Properties
..................................

The ‘uicontextmenu’ properties are:

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘callback’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uicontextmenu’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uicontextmenu is clipped in its parent
     axes limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uicontextmenu has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuicontextmenucreatefcn", 'disp
     ("uicontextmenu created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uicontextmenu is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uicontextmenu’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uicontextmenu processes mouse events or passes them
     to ancestors of the object.  When enabled, the object may respond
     to mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuicontextmenupickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uicontextmenu will accept mouse clicks.  By
     default, ‘pickableparts’ is "visible" and only visible parts of the
     uicontextmenu or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuicontextmenuhittest.

‘position’: def. ‘[0 0]’

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always
     "uicontextmenu"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uicontextmenu object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uicontextmenu is not rendered on screen.


File: octave.info,  Node: Uipanel Properties,  Next: Uicontrol Properties,  Prev: Uicontextmenu Properties,  Up: Graphics Object Properties

15.3.3.13 Uipanel Properties
............................

The ‘uipanel’ properties are:

‘backgroundcolor’: def. ‘[0.93725 0.92157 0.90588]’

‘beingdeleted’: {"off"} | "on"

‘bordertype’: "beveledin" | "beveledout" | {"etchedin"} | "etchedout" | "line" | "none"

‘borderwidth’: def. ‘1’

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uipanel’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uipanel is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uipanel has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuipanelcreatefcn", 'disp ("uipanel
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uipanel is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘fontangle’: "italic" | {"normal"} | "oblique"
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFuipanelfontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | "demi" | "light" | {"normal"}
     Control the variant of the base font used for text rendering.

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uipanel’s handle is not visible
     in its parent’s "children" property.

‘highlightcolor’: def. ‘[1 1 1]’

‘hittest’: "off" | {"on"}
     Specify whether uipanel processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuipanelpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uipanel will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the uipanel
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFuipanelhittest.

‘position’: def. ‘[0 0 1 1]’

‘resizefcn’: def. ‘[](0x0)’

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘shadowcolor’: def. ‘[0.62483 0.61437 0.60391]’

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘title’: def. ""

‘titleposition’: "centerbottom" | "centertop" | "leftbottom" | {"lefttop"} | "rightbottom" | "righttop"

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uipanel"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uipanel object.

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uipanel is not rendered on screen.


File: octave.info,  Node: Uicontrol Properties,  Next: Uitoolbar Properties,  Prev: Uipanel Properties,  Up: Graphics Object Properties

15.3.3.14 Uicontrol Properties
..............................

The ‘uicontrol’ properties are:

‘backgroundcolor’: def. ‘[0.93725 0.92157 0.90588]’

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘callback’: def. ‘[](0x0)’

‘cdata’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uicontrol’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uicontrol is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uicontrol has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuicontrolcreatefcn", 'disp ("uicontrol
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uicontrol is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘enable’: "inactive" | "off" | {"on"}

‘extent’ (read-only): def. ‘[0 0 0 0]’

‘fontangle’: "italic" | {"normal"} | "oblique"
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFuicontrolfontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | "demi" | "light" | {"normal"}
     Control the variant of the base font used for text rendering.

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uicontrol’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uicontrol processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuicontrolpickableparts.

‘horizontalalignment’: {"center"} | "left" | "right"

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘keypressfcn’: def. ‘[](0x0)’

‘listboxtop’: def. ‘1’

‘max’: def. ‘1’

‘min’: def. ‘0’

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uicontrol will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uicontrol or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuicontrolhittest.

‘position’: def. ‘[0 0 80 30]’

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘sliderstep’: def. ‘[0.010000 0.100000]’

‘string’: def. ""

‘style’: "checkbox" | "edit" | "frame" | "listbox" | "popupmenu" | {"pushbutton"} | "radiobutton" | "slider" | "text" | "togglebutton"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tooltipstring’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uicontrol"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uicontrol object.

‘units’: "centimeters" | "characters" | "inches" | "normalized" | {"pixels"} | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘value’: def. ‘0’

‘verticalalignment’: "bottom" | {"middle"} | "top"

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uicontrol is not rendered on screen.


File: octave.info,  Node: Uitoolbar Properties,  Next: Uipushtool Properties,  Prev: Uicontrol Properties,  Up: Graphics Object Properties

15.3.3.15 Uitoolbar Properties
..............................

The ‘uitoolbar’ properties are:

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uitoolbar’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uitoolbar is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uitoolbar has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuitoolbarcreatefcn", 'disp ("uitoolbar
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uitoolbar is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uitoolbar’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uitoolbar processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuitoolbarpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uitoolbar will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uitoolbar or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuitoolbarhittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uitoolbar"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uitoolbar object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uitoolbar is not rendered on screen.


File: octave.info,  Node: Uipushtool Properties,  Next: Uitoggletool Properties,  Prev: Uitoolbar Properties,  Up: Graphics Object Properties

15.3.3.16 Uipushtool Properties
...............................

The ‘uipushtool’ properties are:

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘cdata’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uipushtool’s children.

‘clickedcallback’: def. ‘[](0x0)’

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uipushtool is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uipushtool has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuipushtoolcreatefcn", 'disp ("uipushtool
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uipushtool is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘enable’: "off" | {"on"}

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uipushtool’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uipushtool processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuipushtoolpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uipushtool will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uipushtool or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuipushtoolhittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘separator’: {"off"} | "on"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tooltipstring’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uipushtool"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uipushtool object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uipushtool is not rendered on screen.


File: octave.info,  Node: Uitoggletool Properties,  Prev: Uipushtool Properties,  Up: Graphics Object Properties

15.3.3.17 Uitoggletool Properties
.................................

The ‘uitoggletool’ properties are:

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘cdata’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uitoggletool’s children.

‘clickedcallback’: def. ‘[](0x0)’

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uitoggletool is clipped in its parent
     axes limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uitoggletool has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuitoggletoolcreatefcn", 'disp
     ("uitoggletool created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uitoggletool is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘enable’: "off" | {"on"}

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uitoggletool’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uitoggletool processes mouse events or passes them
     to ancestors of the object.  When enabled, the object may respond
     to mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuitoggletoolpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘offcallback’: def. ‘[](0x0)’

‘oncallback’: def. ‘[](0x0)’

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uitoggletool will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uitoggletool or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuitoggletoolhittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘separator’: {"off"} | "on"

‘state’: {"off"} | "on"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tooltipstring’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uitoggletool"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uitoggletool object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uitoggletool is not rendered on screen.


File: octave.info,  Node: Searching Properties,  Next: Managing Default Properties,  Prev: Graphics Object Properties,  Up: Graphics Data Structures

15.3.4 Searching Properties
---------------------------

 -- : H = findobj ()
 -- : H = findobj (PROP_NAME, PROP_VALUE, ...)
 -- : H = findobj (PROP_NAME, PROP_VALUE, "-LOGICAL_OP", PROP_NAME,
          PROP_VALUE)
 -- : H = findobj ("-property", PROP_NAME)
 -- : H = findobj ("-regexp", PROP_NAME, PATTERN)
 -- : H = findobj (HLIST, ...)
 -- : H = findobj (HLIST, "flat", ...)
 -- : H = findobj (HLIST, "-depth", D, ...)
     Find graphics objects with specified properties.

     When called without arguments, return all graphic objects beginning
     with the root object (0) and including all of its descendants.

     The simplest form for narrowing the results is

          findobj (PROP_NAME, PROP_VALUE)

     which returns the handles of all objects which have a property
     named PROP_NAME that has the value PROP_VALUE.  If multiple
     property/value pairs are specified then only objects meeting all of
     the conditions (equivalent to ‘-and’) are returned.

     The search can be limited to a particular set of objects and their
     descendants, by passing a handle or set of handles HLIST as the
     first argument.

     The depth of the object hierarchy to search can be limited with the
     "-depth" argument.  An example of searching through only three
     generations of children is:

          findobj (HLIST, "-depth", 3, PROP_NAME, PROP_VALUE)

     Specifying a depth D of 0 limits the search to the set of objects
     passed in HLIST.  A depth of 0 is also equivalent to the "flat"
     argument.  The default depth value is ‘Inf’ which includes all
     descendants.

     A specified logical operator may be used between PROP_NAME,
     PROP_VALUE pairs.  The supported logical operators are: "-and",
     "-or", "-xor", "-not".  Example code to locate all figure and axes
     objects is

          findobj ("type", "figure", "-or", "type", "axes")

     Objects may also be matched by comparing a regular expression to
     the property values, where property values that match ‘regexp
     (PROP_VALUE, PATTERN)’ are returned.

     Finally, objects which have a property name can be found with the
     "-property" option.  For example, code to locate objects with a
     "meshstyle" property is

          findobj ("-property", "meshstyle")

     Implementation Note: The search only includes objects with visible
     handles (HandleVisibility = "on").  *Note findall: XREFfindall, to
     search for all objects including hidden ones.

     See also: *note findall: XREFfindall, *note allchild: XREFallchild,
     *note get: XREFget, *note set: XREFset.

 -- : H = findall ()
 -- : H = findall (PROP_NAME, PROP_VALUE, ...)
 -- : H = findall (PROP_NAME, PROP_VALUE, "-LOGICAL_OP", PROP_NAME,
          PROP_VALUE)
 -- : H = findall ("-property", PROP_NAME)
 -- : H = findall ("-regexp", PROP_NAME, PATTERN)
 -- : H = findall (HLIST, ...)
 -- : H = findall (HLIST, "flat", ...)
 -- : H = findall (HLIST, "-depth", D, ...)
     Find graphics object, including hidden ones, with specified
     properties.

     The return value H is a list of handles to the found graphic
     objects.

     ‘findall’ performs the same search as ‘findobj’, but it includes
     hidden objects (HandleVisibility = "off").  For full documentation,
     *note findobj: XREFfindobj.

     See also: *note findobj: XREFfindobj, *note allchild: XREFallchild,
     *note get: XREFget, *note set: XREFset.


File: octave.info,  Node: Managing Default Properties,  Prev: Searching Properties,  Up: Graphics Data Structures

15.3.5 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, of the specified object type.
For example, setting the default ‘color’ property of ‘line’ objects to
"green", for the ‘root’ object, will result in all ‘line’ objects
inheriting the ‘color’ "green" as the default value.

     set (groot, "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 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 (groot, "defaultlinecolor", "red");
     set (1, "defaultlinecolor", "green");
     set (gca (), "defaultlinecolor", "blue");
     line (1:10, rand (1, 10));
     subplot (2, 1, 2);
     line (1:10, rand (1, 10));
     figure (2)
     line (1:10, rand (1, 10));

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 (H)
     Reset the properties of the graphic object H to their default
     values.

     For figures, the properties "position", "units", "windowstyle", and
     "paperunits" are not affected.  For axes, the properties "position"
     and "units" are not affected.

     The input H may also be a vector of graphic handles in which case
     each individual object will be reset.

     See also: *note cla: XREFcla, *note clf: XREFclf, *note newplot:
     XREFnewplot.

   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 (groot, "factory");

returns a list of factory defaults.


File: octave.info,  Node: Advanced Plotting,  Prev: Graphics Data Structures,  Up: Plotting

15.4 Advanced Plotting
======================

* Menu:

* Colors::
* Line Styles::
* Marker Styles::
* Callbacks::
* Application-defined Data::
* Object Groups::
* Transform Groups::
* Graphics Toolkits::


File: octave.info,  Node: Colors,  Next: Line Styles,  Up: Advanced Plotting

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


File: octave.info,  Node: Line Styles,  Next: Marker Styles,  Prev: Colors,  Up: Advanced Plotting

15.4.2 Line Styles
------------------

Line styles are specified by the following properties:

‘linestyle’
     May be one of

     "-"
          Solid line.  [default]

     "--"
          Dashed line.

     ":"
          Dotted line.

     "-."
          A dash-dot line.

     "none"
          No line.  Points will still be marked using the current Marker
          Style.

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


File: octave.info,  Node: Marker Styles,  Next: Callbacks,  Prev: Line Styles,  Up: Advanced Plotting

15.4.3 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.  *Note Colors::.

‘markerfacecolor’
     The color of the marker, or "none" to indicate that the marker
     should not be filled.  *Note 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.

   The ‘colstyle’ function will parse a ‘plot’-style specification and
will return the color, line, and marker values that would result.

 -- : [STYLE, COLOR, MARKER, MSG] = colstyle (STYLE)
     Parse the line specification STYLE and return the line style,
     color, and markers given.

     In the case of an error, the string MSG will return the text of the
     error.


File: octave.info,  Node: Callbacks,  Next: Application-defined Data,  Prev: Marker Styles,  Up: Advanced Plotting

15.4.4 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 (hsrc, evt)
       ...
     endfunction

where ‘hsrc’ is a handle to the source of the callback, and ‘evt’ gives
some event specific data.

   The function can be provided as a function handle to a plain Octave
function, as an anonymous function, or as a string representing an
Octave command.  The latter syntax is not recommended since syntax
errors will only occur when the string is evaluated.  *Note Function
Handles section: Function Handles Anonymous Functions Inline Functions.

   This can then be associated with an object either at the object’s
creation, or later with the ‘set’ function.  For example,

     plot (x, "DeleteFcn", @(h, 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 two default arguments.  For example:

     plot (x, "DeleteFcn", {@mycallback, "1"})
     ...
     function mycallback (h, evt, arg1)
       fprintf ("Closing plot %d\n", arg1);
     endfunction

   *Caution:* The second argument in callback functions—‘evt’—is only
partially implemented in the Qt graphics toolkit:

   • Mouse click events: ‘evt’ is a class ‘double’ value: 1 for left, 2
     for middle, and 3 for right click.

   • Key press events: ‘evt’ is a structure with fields ‘Key’ (string),
     ‘Character’ (string), and ‘Modifier’ (cell array of strings).

   • Other events: ‘evt’ is a class ‘double’ empty matrix.

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

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

   • DeleteFcn: called at the moment an object is deleted.

   • ButtonDownFcn: called if a mouse button is pressed while the
     pointer is over this object.  Note, that the gnuplot interface does
     not implement this callback.

   By default callback functions are queued (they are executed one after
the other in the event queue) unless the ‘drawnow’, ‘figure’, ‘waitfor’,
‘getframe’, or ‘pause’ functions are used.  If an executing callback
invokes one of those functions, it causes Octave to flush the event
queue, which results in the executing callback being interrupted.

   It is possible to specify that an object’s callbacks should not be
interrupted by setting the object’s ‘interruptible’ property to "off".
In this case, Octave decides what to do based on the ‘busyaction’
property of the *interrupting* callback object:

‘queue’ (the default)
     The interrupting callback is executed after the executing callback
     has returned.

‘cancel’
     The interrupting callback is discarded.

   The ‘interruptible’ property has no effect when the interrupting
callback is a ‘deletefcn’, or a figure ‘resizefcn’ or ‘closerequestfcn’.
Those callbacks always interrupt the executing callback.

   The handle to the object that holds the callback being executed can
be obtained with the ‘gcbo’ function.  The handle to the ancestor figure
of this object may be obtained using the ‘gcbf’ function.

 -- : H = gcbo ()
 -- : [H, FIG] = gcbo ()
     Return a handle to the object whose callback is currently
     executing.

     If no callback is executing, this function returns the empty
     matrix.  This handle is obtained from the root object property
     "CallbackObject".

     When called with a second output argument, return the handle of the
     figure containing the object whose callback is currently executing.
     If no callback is executing the second output is also set to the
     empty matrix.

     See also: *note gcbf: XREFgcbf, *note gco: XREFgco, *note gca:
     XREFgca, *note gcf: XREFgcf, *note get: XREFget, *note set:
     XREFset.

 -- : FIG = gcbf ()
     Return a handle to the figure containing the object whose callback
     is currently executing.

     If no callback is executing, this function returns the empty
     matrix.  The handle returned by this function is the same as the
     second output argument of ‘gcbo’.

     See also: *note gcbo: XREFgcbo, *note gcf: XREFgcf, *note gco:
     XREFgco, *note gca: XREFgca, *note get: XREFget, *note set:
     XREFset.

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


File: octave.info,  Node: Application-defined Data,  Next: Object Groups,  Prev: Callbacks,  Up: Advanced Plotting

15.4.5 Application-defined Data
-------------------------------

Octave has a provision for attaching application-defined data to a
graphics handle.  The data can be anything which is meaningful to the
application, and will be completely ignored by Octave.

 -- : setappdata (H, NAME, VALUE)
 -- : setappdata (H, NAME1, VALUE1, NAME2, VALUE3, ...)
 -- : setappdata (H, {NAME1, NAME2, ...}, {VALUE1, VALUE2, ...})
     Set the application data NAME to VALUE for the graphics object with
     handle H.

     H may also be a vector of graphics handles.  If the application
     data with the specified NAME does not exist, it is created.

     Multiple NAME/VALUE pairs can be specified.  Alternatively, a cell
     array of NAMES and a corresponding cell array of VALUES can be
     specified.

     See also: *note getappdata: XREFgetappdata, *note isappdata:
     XREFisappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.

 -- : VALUE = getappdata (H, NAME)
 -- : APPDATA = getappdata (H)
     Return the VALUE of the application data NAME for the graphics
     object with handle H.

     H may also be a vector of graphics handles.  If no second argument
     NAME is given then ‘getappdata’ returns a structure, APPDATA, whose
     fields correspond to the appdata properties.

     See also: *note setappdata: XREFsetappdata, *note isappdata:
     XREFisappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.

 -- : rmappdata (H, NAME)
 -- : rmappdata (H, NAME1, NAME2, ...)
     Delete the application data NAME from the graphics object with
     handle H.

     H may also be a vector of graphics handles.  Multiple application
     data names may be supplied to delete several properties at once.

     See also: *note setappdata: XREFsetappdata, *note getappdata:
     XREFgetappdata, *note isappdata: XREFisappdata.

 -- : VALID = isappdata (H, NAME)
     Return true if the named application data, NAME, exists for the
     graphics object with handle H.

     H may also be a vector of graphics handles.

     See also: *note getappdata: XREFgetappdata, *note setappdata:
     XREFsetappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.


File: octave.info,  Node: Object Groups,  Next: Transform Groups,  Prev: Application-defined Data,  Up: Advanced Plotting

15.4.6 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 ()
 -- : hggroup (HAX)
 -- : hggroup (..., PROPERTY, VALUE, ...)
 -- : H = hggroup (...)
     Create handle graphics group object with axes parent HAX.

     If no parent is specified, the group is created in the current
     axes.

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

     The optional return value H is a graphics handle to the created
     hggroup object.

     Programming Note: An hggroup is a way to group base graphics
     objects such as line objects or patch objects into a single unit
     which can react appropriately.  For example, the individual lines
     of a contour plot are collected into a single hggroup so that they
     can be made visible/invisible with a single command, ‘set
     (hg_handle, "visible", "off")’.

     See also: *note addproperty: XREFaddproperty, *note addlistener:
     XREFaddlistener.

   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 (NAME, H, TYPE)
 -- : addproperty (NAME, H, TYPE, ARG, ...)
     Create a new property named NAME in graphics object H.

     TYPE determines the type of the property to create.  ARGS usually
     contains the default value of the property, but additional
     arguments might be given, depending on the type of the property.

     The supported property types are:

     ‘string’
          A string property.  ARG contains the default string value.

     ‘any’
          An un-typed property.  This kind of property can hold any
          octave value.  ARGS contains the default value.

     ‘radio’
          A string property with a limited set of accepted values.  The
          first argument must be a string with all accepted values
          separated by a vertical bar (’|’).  The default value can be
          marked by enclosing it with a ’{’ ’}’ pair.  The default value
          may also be given as an optional second string argument.

     ‘boolean’
          A boolean property.  This property type is equivalent to a
          radio property with "on|off" as accepted values.  ARG contains
          the default property value.

     ‘double’
          A scalar double property.  ARG contains the default value.

     ‘handle’
          A handle property.  This kind of property holds the handle of
          a graphics object.  ARG contains the default handle value.
          When no default value is given, the property is initialized to
          the empty matrix.

     ‘data’
          A data (matrix) property.  ARG contains the default data
          value.  When no default value is given, the data is
          initialized to the empty matrix.

     ‘color’
          A color property.  ARG contains the default color value.  When
          no default color is given, the property is set to black.  An
          optional second string argument may be given to specify an
          additional set of accepted string values (like a radio
          property).

     TYPE may also be the concatenation of a core object type and a
     valid property name for that object type.  The property created
     then has the same characteristics as the referenced property (type,
     possible values, hidden state...).  This allows one to clone an
     existing property into the graphics object H.

     Examples:

          addproperty ("my_property", gcf, "string", "a string value");
          addproperty ("my_radio", gcf, "radio", "val_1|val_2|{val_3}");
          addproperty ("my_style", gcf, "linelinestyle", "--");

     See also: *note addlistener: XREFaddlistener, *note hggroup:
     XREFhggroup.

   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 (H, PROP, FCN)
     Register FCN as listener for the property PROP of the graphics
     object H.

     Property listeners are executed (in order of registration) when the
     property is set.  The new value is already available when the
     listeners are executed.

     PROP must be a string naming a valid property in H.

     FCN can be a function handle, a string or a cell array whose first
     element is a function handle.  If FCN is a function handle, the
     corresponding function should accept at least 2 arguments, that
     will be set to the object handle and the empty matrix respectively.
     If FCN is a string, it must be any valid octave expression.  If FCN
     is a cell array, the first element must be a function handle with
     the same signature as described above.  The next elements of the
     cell array are passed as additional arguments to the function.

     Example:

          function my_listener (h, dummy, p1)
            fprintf ("my_listener called with p1=%s\n", p1);
          endfunction

          addlistener (gcf, "position", {@my_listener, "my string"})

     See also: *note dellistener: XREFdellistener, *note addproperty:
     XREFaddproperty, *note hggroup: XREFhggroup.

 -- : dellistener (H, PROP, FCN)
     Remove the registration of FCN as a listener for the property PROP
     of the graphics object H.

     The function FCN must be the same variable (not just the same
     value), as was passed to the original call to ‘addlistener’.

     If FCN is not defined then all listener functions of PROP are
     removed.

     Example:

          function my_listener (h, dummy, p1)
            fprintf ("my_listener called with p1=%s\n", p1);
          endfunction

          c = {@my_listener, "my string"};
          addlistener (gcf, "position", c);
          dellistener (gcf, "position", c);

     See also: *note addlistener: XREFaddlistener.

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

 -- : HLINK = linkprop (H, "PROP")
 -- : HLINK = linkprop (H, {"PROP1", "PROP2", ...})
     Link graphic object properties, such that a change in one is
     propagated to the others.

     The input H is a vector of graphic handles to link.

     PROP may be a string when linking a single property, or a cell
     array of strings for multiple properties.  During the linking
     process all properties in PROP will initially be set to the values
     that exist on the first object in the list H.

     The function returns HLINK which is a special object describing the
     link.  As long as the reference HLINK exists, the link between
     graphic objects will be active.  This means that HLINK must be
     preserved in a workspace variable, a global variable, or otherwise
     stored using a function such as ‘setappdata’ or ‘guidata’.  To
     unlink properties, execute ‘clear HLINK’.

     An example of the use of ‘linkprop’ is

          x = 0:0.1:10;
          subplot (1,2,1);
          h1 = plot (x, sin (x));
          subplot (1,2,2);
          h2 = plot (x, cos (x));
          hlink = linkprop ([h1, h2], {"color","linestyle"});
          set (h1, "color", "green");
          set (h2, "linestyle", "--");

     See also: *note linkaxes: XREFlinkaxes, *note addlistener:
     XREFaddlistener.

 -- : linkaxes (HAX)
 -- : linkaxes (HAX, OPTSTR)
     Link the axis limits of 2-D plots such that a change in one is
     propagated to the others.

     The axes handles to be linked are passed as the first argument HAX.

     The optional second argument is a string which defines which axis
     limits will be linked.  The possible values for OPTSTR are:

     "x"
          Link x-axes

     "y"
          Link y-axes

     "xy" (default)
          Link both axes

     "off"
          Turn off linking

     If unspecified the default is to link both X and Y axes.

     When linking, the limits from the first axes in HAX are applied to
     the other axes in the list.  Subsequent changes to any one of the
     axes will be propagated to the others.

     See also: *note linkprop: XREFlinkprop, *note addproperty:
     XREFaddproperty.

   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.

* Menu:

* Data Sources in Object Groups::
* Area Series::
* Bar Series::
* Contour Groups::
* Error Bar Series::
* Line Series::
* Quiver Group::
* Scatter Group::
* Stair Group::
* Stem Series::
* Surface Group::


File: octave.info,  Node: Data Sources in Object Groups,  Next: Area Series,  Up: Object Groups

15.4.6.1 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 ()
 -- : refreshdata (H)
 -- : refreshdata (H, WORKSPACE)
     Evaluate any ‘datasource’ properties of the current figure and
     update the plot if the corresponding data has changed.

     If the first argument H is a list of graphic handles, then operate
     on these objects rather than the current figure returned by ‘gcf’.

     The optional second argument WORKSPACE can take the following
     values:

     "base"
          Evaluate the datasource properties in the base workspace.
          (default).

     "caller"
          Evaluate the datasource properties in the workspace of the
          function that called ‘refreshdata’.

     An example of the use of ‘refreshdata’ is:

          x = 0:0.1:10;
          y = sin (x);
          plot (x, y, "ydatasource", "y");
          for i = 1 : 100
            pause (0.1);
            y = sin (x + 0.1*i);
            refreshdata ();
          endfor


File: octave.info,  Node: Area Series,  Next: Bar Series,  Prev: Data Sources in Object Groups,  Up: Object Groups

15.4.6.2 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.  *Note Line Styles::.

‘edgecolor’
‘facecolor’
     The line and fill color of the patch objects making up the areas.
     *Note 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.


File: octave.info,  Node: Bar Series,  Next: Contour Groups,  Prev: Area Series,  Up: Object Groups

15.4.6.3 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 properties are propagated to the other
     members of the bar series and to the baseline itself.  Equally,
     changes in the properties of the base line itself are propagated to
     the members of the corresponding bar series.

‘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.  *Note Line Styles::.

‘edgecolor’
‘facecolor’
     The line and fill color of the patch objects making up the bars.
     *Note 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.


File: octave.info,  Node: Contour Groups,  Next: Error Bar Series,  Prev: Bar Series,  Up: Object Groups

15.4.6.4 Contour Groups
.......................

Contour group objects are created by the ‘contour’, ‘contourf’, and
‘contour3’ functions.  The are also 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 (*note
     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.


File: octave.info,  Node: Error Bar Series,  Next: Line Series,  Prev: Contour Groups,  Up: Object Groups

15.4.6.5 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.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the error bars.
     *Note Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the error bars.  *Note
     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.


File: octave.info,  Node: Line Series,  Next: Quiver Group,  Prev: Error Bar Series,  Up: Object Groups

15.4.6.6 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.  *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects.  *Note Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers.  *Note Colors::.

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

‘xdatasource’
‘ydatasource’
‘zdatasource’
     Data source variables.


File: octave.info,  Node: Quiver Group,  Next: Scatter Group,  Prev: Line Series,  Up: Object Groups

15.4.6.7 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.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the quiver.  *Note
     Line Styles::.

‘marker’
‘markerfacecolor’
‘markersize’
     The line and fill color of the marker objects at the original of
     the arrows.  *Note 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.


File: octave.info,  Node: Scatter Group,  Next: Stair Group,  Prev: Quiver Group,  Up: Object Groups

15.4.6.8 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.  *Note Line
     Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
     The line and fill color of the markers of the points.  *Note
     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.


File: octave.info,  Node: Stair Group,  Next: Stem Series,  Prev: Scatter Group,  Up: Object Groups

15.4.6.9 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.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the stairs.  *Note
     Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the stairs.  *Note
     Colors::.

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

‘xdatasource’
‘ydatasource’
     Data source variables.


File: octave.info,  Node: Stem Series,  Next: Surface Group,  Prev: Stair Group,  Up: Object Groups

15.4.6.10 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.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the stems.  *Note
     Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the stems.  *Note
     Colors::.

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

‘xdatasource’
‘ydatasource’
‘zdatasource’
     Data source variables.


File: octave.info,  Node: Surface Group,  Prev: Stem Series,  Up: Object Groups

15.4.6.11 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.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the lines on the surface.  *Note Line
     Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the surface.  *Note
     Colors::.

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

‘xdatasource’
‘ydatasource’
‘zdatasource’
‘cdatasource’
     Data source variables.


File: octave.info,  Node: Transform Groups,  Next: Graphics Toolkits,  Prev: Object Groups,  Up: Advanced Plotting

15.4.7 Transform Groups
-----------------------

 -- : H = hgtransform ()
 -- : H = hgtransform (PROPERTY, VALUE, ...)
 -- : H = hgtransform (HAX, ...)

     Create a graphics transform object.

     FIXME: Need to write documentation.  FIXME: Add ’makehgtform’ to
     seealso list when it is implemented.

     See also: *note hggroup: XREFhggroup.


File: octave.info,  Node: Graphics Toolkits,  Prev: Transform Groups,  Up: Advanced Plotting

15.4.8 Graphics Toolkits
------------------------

 -- : NAME = graphics_toolkit ()
 -- : NAME = graphics_toolkit (HLIST)
 -- : graphics_toolkit (NAME)
 -- : graphics_toolkit (HLIST, NAME)
     Query or set the default graphics toolkit which is assigned to new
     figures.

     With no inputs, return the current default graphics toolkit.  If
     the input is a list of figure graphic handles, HLIST, then return
     the name of the graphics toolkit in use for each figure.

     When called with a single input NAME set the default graphics
     toolkit to NAME.  If the toolkit is not already loaded, it is
     initialized by calling the function ‘__init_NAME__’.  If the first
     input is a list of figure handles, HLIST, then the graphics toolkit
     is set to NAME for these figures only.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

 -- : available_graphics_toolkits ()
     Return a cell array of registered graphics toolkits.

     See also: *note graphics_toolkit: XREFgraphics_toolkit, *note
     register_graphics_toolkit: XREFregister_graphics_toolkit.

 -- : loaded_graphics_toolkits ()
     Return a cell array of the currently loaded graphics toolkits.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

 -- : register_graphics_toolkit (TOOLKIT)
     List TOOLKIT as an available graphics toolkit.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

* Menu:

* Customizing Toolkit Behavior::


File: octave.info,  Node: Customizing Toolkit Behavior,  Up: Graphics Toolkits

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

 -- : [PROG, ARGS] = gnuplot_binary ()
 -- : [OLD_PROG, OLD_ARGS] = gnuplot_binary (NEW_PROG)
 -- : [OLD_PROG, OLD_ARGS] = gnuplot_binary (NEW_PROG, ARG1, ...)
     Query or set the name of the program invoked by the plot command
     when the graphics toolkit is set to "gnuplot".

     Additional arguments to pass to the external plotting program may
     also be given.  The default value is "gnuplot" with no additional
     arguments.  *Note Installation::.

     See also: *note graphics_toolkit: XREFgraphics_toolkit.


File: octave.info,  Node: Matrix Manipulation,  Next: Arithmetic,  Prev: Plotting,  Up: Top

16 Matrix Manipulation
**********************

There are a number of functions available for checking to see if the
elements of a matrix meet some condition, and for rearranging the
elements of a matrix.  For example, Octave can easily tell you if all
the elements of a matrix are finite, or are less than some specified
value.  Octave can also rotate the elements, extract the upper- or
lower-triangular parts, or sort the columns of a matrix.

* Menu:

* Finding Elements and Checking Conditions::
* Rearranging Matrices::
* Special Utility Matrices::
* Famous Matrices::


File: octave.info,  Node: Finding Elements and Checking Conditions,  Next: Rearranging Matrices,  Up: Matrix Manipulation

16.1 Finding Elements and Checking Conditions
=============================================

The functions ‘any’ and ‘all’ are useful for determining whether any or
all of the elements of a matrix satisfy some condition.  The ‘find’
function is also useful in determining which elements of a matrix meet a
specified condition.

 -- : any (X)
 -- : any (X, DIM)
     For a vector argument, return true (logical 1) if any element of
     the vector is nonzero.

     For a matrix argument, return a row vector of logical ones and
     zeros with each element indicating whether any of the elements of
     the corresponding column of the matrix are nonzero.  For example:

          any (eye (2, 4))
           ⇒ [ 1, 1, 0, 0 ]

     If the optional argument DIM is supplied, work along dimension DIM.
     For example:

          any (eye (2, 4), 2)
           ⇒ [ 1; 1 ]

     See also: *note all: XREFall.

 -- : all (X)
 -- : all (X, DIM)
     For a vector argument, return true (logical 1) if all elements of
     the vector are nonzero.

     For a matrix argument, return a row vector of logical ones and
     zeros with each element indicating whether all of the elements of
     the corresponding column of the matrix are nonzero.  For example:

          all ([2, 3; 1, 0])
              ⇒ [ 1, 0 ]

     If the optional argument DIM is supplied, work along dimension DIM.

     See also: *note any: XREFany.

   Since the comparison operators (*note Comparison Ops::) return
matrices of ones and zeros, it is easy to test a matrix for many things,
not just whether the elements are nonzero.  For example,

     all (all (rand (5) < 0.9))
          ⇒ 0

tests a random 5 by 5 matrix to see if all of its elements are less than
0.9.

   Note that in conditional contexts (like the test clause of ‘if’ and
‘while’ statements) Octave treats the test as if you had typed ‘all (all
(condition))’.

 -- : Z = xor (X, Y)
 -- : Z = xor (X1, X2, ...)
     Return the “exclusive or” of X and Y.

     For boolean expressions X and Y, ‘xor (X, Y)’ is true if and only
     if one of X or Y is true.  Otherwise, if X and Y are both true or
     both false, ‘xor’ returns false.

     The truth table for the xor operation is

                                      X  Y    Z
                                      -  -    -
                                      0  0    0
                                      1  0    1
                                      0  1    1
                                      1  1    0

     If more than two arguments are given the xor operation is applied
     cumulatively from left to right:

          (...((x1 XOR x2) XOR x3) XOR ...)

     See also: *note and: XREFand, *note or: XREFor, *note not: XREFnot.

 -- : diff (X)
 -- : diff (X, K)
 -- : diff (X, K, DIM)
     If X is a vector of length n, ‘diff (X)’ is the vector of first
     differences X(2) - X(1), ..., X(n) - X(n-1).

     If X is a matrix, ‘diff (X)’ is the matrix of column differences
     along the first non-singleton dimension.

     The second argument is optional.  If supplied, ‘diff (X, K)’, where
     K is a non-negative integer, returns the K-th differences.  It is
     possible that K is larger than the first non-singleton dimension of
     the matrix.  In this case, ‘diff’ continues to take the differences
     along the next non-singleton dimension.

     The dimension along which to take the difference can be explicitly
     stated with the optional variable DIM.  In this case the K-th order
     differences are calculated along this dimension.  In the case where
     K exceeds ‘size (X, DIM)’ an empty matrix is returned.

     See also: *note sort: XREFsort, *note merge: XREFmerge.

 -- : isinf (X)
     Return a logical array which is true where the elements of X are
     infinite and false where they are not.

     For example:

          isinf ([13, Inf, NA, NaN])
                ⇒ [ 0, 1, 0, 0 ]

     See also: *note isfinite: XREFisfinite, *note isnan: XREFisnan,
     *note isna: XREFisna.

 -- : isnan (X)
     Return a logical array which is true where the elements of X are
     NaN values and false where they are not.

     NA values are also considered NaN values.  For example:

          isnan ([13, Inf, NA, NaN])
                ⇒ [ 0, 0, 1, 1 ]

     See also: *note isna: XREFisna, *note isinf: XREFisinf, *note
     isfinite: XREFisfinite.

 -- : isfinite (X)
     Return a logical array which is true where the elements of X are
     finite values and false where they are not.

     For example:

          isfinite ([13, Inf, NA, NaN])
               ⇒ [ 1, 0, 0, 0 ]

     See also: *note isinf: XREFisinf, *note isnan: XREFisnan, *note
     isna: XREFisna.

 -- : [ERR, YI, ...] = common_size (XI, ...)
     Determine if all input arguments are either scalar or of common
     size.

     If true, ERR is zero, and YI is a matrix of the common size with
     all entries equal to XI if this is a scalar or XI otherwise.  If
     the inputs cannot be brought to a common size, ERR is 1, and YI is
     XI.  For example:

          [err, a, b] = common_size ([1 2; 3 4], 5)
               ⇒ err = 0
               ⇒ a = [ 1, 2; 3, 4 ]
               ⇒ b = [ 5, 5; 5, 5 ]

     This is useful for implementing functions where arguments can
     either be scalars or of common size.

     See also: *note size: XREFsize, *note size_equal: XREFsize_equal,
     *note numel: XREFnumel, *note ndims: XREFndims.

 -- : IDX = find (X)
 -- : IDX = find (X, N)
 -- : IDX = find (X, N, DIRECTION)
 -- : [i, j] = find (...)
 -- : [i, j, v] = find (...)
     Return a vector of indices of nonzero elements of a matrix, as a
     row if X is a row vector or as a column otherwise.

     To obtain a single index for each matrix element, Octave pretends
     that the columns of a matrix form one long vector (like Fortran
     arrays are stored).  For example:

          find (eye (2))
            ⇒ [ 1; 4 ]

     If two inputs are given, N indicates the maximum number of elements
     to find from the beginning of the matrix or vector.

     If three inputs are given, DIRECTION should be one of "first" or
     "last", requesting only the first or last N indices, respectively.
     However, the indices are always returned in ascending order.

     If two outputs are requested, ‘find’ returns the row and column
     indices of nonzero elements of a matrix.  For example:

          [i, j] = find (2 * eye (2))
              ⇒ i = [ 1; 2 ]
              ⇒ j = [ 1; 2 ]

     If three outputs are requested, ‘find’ also returns a vector
     containing the nonzero values.  For example:

          [i, j, v] = find (3 * eye (2))
                 ⇒ i = [ 1; 2 ]
                 ⇒ j = [ 1; 2 ]
                 ⇒ v = [ 3; 3 ]

     Note that this function is particularly useful for sparse matrices,
     as it extracts the nonzero elements as vectors, which can then be
     used to create the original matrix.  For example:

          sz = size (a);
          [i, j, v] = find (a);
          b = sparse (i, j, v, sz(1), sz(2));

     See also: *note nonzeros: XREFnonzeros.

 -- : IDX = lookup (TABLE, Y)
 -- : IDX = lookup (TABLE, Y, OPT)
     Lookup values in a *sorted* table.

     This function is usually used as a prelude to interpolation.

     If table is increasing, of length N and ‘idx = lookup (table, y)’,
     then ‘table(idx(i)) <= y(i) < table(idx(i+1))’ for all ‘y(i)’
     within the table.  If ‘y(i) < table(1)’ then ‘idx(i)’ is 0.  If
     ‘y(i) >= table(end)’ or ‘isnan (y(i))’ then ‘idx(i)’ is N.

     If the table is decreasing, then the tests are reversed.  For
     non-strictly monotonic tables, empty intervals are always skipped.
     The result is undefined if TABLE is not monotonic, or if TABLE
     contains a NaN.

     The complexity of the lookup is O(M*log(N)) where M is the size of
     Y.  In the special case when Y is also sorted, the complexity is
     O(min (M*log(N), M+N)).

     TABLE and Y can also be cell arrays of strings (or Y can be a
     single string).  In this case, string lookup is performed using
     lexicographical comparison.

     If OPTS is specified, it must be a string with letters indicating
     additional options.

     ‘m’
          Match.  ‘table(idx(i)) == y(i)’ if ‘y(i)’ occurs in table;
          otherwise, ‘idx(i)’ is zero.

     ‘b’
          Boolean.  ‘idx(i)’ is a logical 1 or 0, indicating whether
          ‘y(i)’ is contained in table or not.

     ‘l’
          Left.  For numeric lookups the leftmost subinterval shall be
          extended to minus infinity (i.e., all indices at least 1).

     ‘r’
          Right.  For numeric lookups the rightmost subinterval shall be
          extended to infinity (i.e., all indices at most N-1).

     *Note*: If TABLE is not sorted the results from ‘lookup’ will be
     unpredictable.

   If you wish to check if a variable exists at all, instead of
properties its elements may have, consult *note Status of Variables::.


File: octave.info,  Node: Rearranging Matrices,  Next: Special Utility Matrices,  Prev: Finding Elements and Checking Conditions,  Up: Matrix Manipulation

16.2 Rearranging Matrices
=========================

 -- : fliplr (X)
     Flip array left to right.

     Return a copy of X with the order of the columns reversed.  In
     other words, X is flipped left-to-right about a vertical axis.  For
     example:

          fliplr ([1, 2; 3, 4])
               ⇒  2  1
                   4  3

     See also: *note flipud: XREFflipud, *note flip: XREFflip, *note
     rot90: XREFrot90, *note rotdim: XREFrotdim.

 -- : flipud (X)
     Flip array upside down.

     Return a copy of X with the order of the rows reversed.  In other
     words, X is flipped upside-down about a horizontal axis.  For
     example:

          flipud ([1, 2; 3, 4])
               ⇒  3  4
                   1  2

     See also: *note fliplr: XREFfliplr, *note flip: XREFflip, *note
     rot90: XREFrot90, *note rotdim: XREFrotdim.

 -- : flip (X)
 -- : flip (X, DIM)
     Flip array across dimension DIM.

     Return a copy of X flipped about the dimension DIM.  DIM defaults
     to the first non-singleton dimension.  For example:

          flip ([1  2  3  4])
                ⇒  4  3  2  1

          flip ([1; 2; 3; 4])
                ⇒  4
                    3
                    2
                    1

          flip ([1 2; 3 4])
                ⇒  3  4
                    1  2

          flip ([1 2; 3 4], 2)
                ⇒  2  1
                    4  3

     See also: *note fliplr: XREFfliplr, *note flipud: XREFflipud, *note
     rot90: XREFrot90, *note rotdim: XREFrotdim, *note permute:
     XREFpermute, *note transpose: XREFtranspose.

 -- : rot90 (A)
 -- : rot90 (A, K)
     Rotate array by 90 degree increments.

     Return a copy of A with the elements rotated counterclockwise in
     90-degree increments.

     The second argument is optional, and specifies how many 90-degree
     rotations are to be applied (the default value is 1).  Negative
     values of K rotate the matrix in a clockwise direction.  For
     example,

          rot90 ([1, 2; 3, 4], -1)
              ⇒  3  1
                  4  2

     rotates the given matrix clockwise by 90 degrees.  The following
     are all equivalent statements:

          rot90 ([1, 2; 3, 4], -1)
          rot90 ([1, 2; 3, 4], 3)
          rot90 ([1, 2; 3, 4], 7)

     The rotation is always performed on the plane of the first two
     dimensions, i.e., rows and columns.  To perform a rotation on any
     other plane, use ‘rotdim’.

     See also: *note rotdim: XREFrotdim, *note fliplr: XREFfliplr, *note
     flipud: XREFflipud, *note flip: XREFflip.

 -- : rotdim (X)
 -- : rotdim (X, N)
 -- : rotdim (X, N, PLANE)
     Return a copy of X with the elements rotated counterclockwise in
     90-degree increments.

     The second argument N is optional, and specifies how many 90-degree
     rotations are to be applied (the default value is 1).  Negative
     values of N rotate the matrix in a clockwise direction.

     The third argument is also optional and defines the plane of the
     rotation.  If present, PLANE is a two element vector containing two
     different valid dimensions of the matrix.  When PLANE is not given
     the first two non-singleton dimensions are used.

     For example,

          rotdim ([1, 2; 3, 4], -1, [1, 2])
               ⇒  3  1
                   4  2

     rotates the given matrix clockwise by 90 degrees.  The following
     are all equivalent statements:

          rotdim ([1, 2; 3, 4], -1, [1, 2])
          rotdim ([1, 2; 3, 4], 3, [1, 2])
          rotdim ([1, 2; 3, 4], 7, [1, 2])

     See also: *note rot90: XREFrot90, *note fliplr: XREFfliplr, *note
     flipud: XREFflipud, *note flip: XREFflip.

 -- : cat (DIM, ARRAY1, ARRAY2, ..., ARRAYN)
     Return the concatenation of N-D array objects, ARRAY1, ARRAY2, ...,
     ARRAYN along dimension DIM.

          A = ones (2, 2);
          B = zeros (2, 2);
          cat (2, A, B)
            ⇒ 1 1 0 0
               1 1 0 0

     Alternatively, we can concatenate A and B along the second
     dimension in the following way:

          [A, B]

     DIM can be larger than the dimensions of the N-D array objects and
     the result will thus have DIM dimensions as the following example
     shows:

          cat (4, ones (2, 2), zeros (2, 2))
            ⇒ ans(:,:,1,1) =

                 1 1
                 1 1

               ans(:,:,1,2) =

                 0 0
                 0 0

     See also: *note horzcat: XREFhorzcat, *note vertcat: XREFvertcat.

 -- : horzcat (ARRAY1, ARRAY2, ..., ARRAYN)
     Return the horizontal concatenation of N-D array objects, ARRAY1,
     ARRAY2, ..., ARRAYN along dimension 2.

     Arrays may also be concatenated horizontally using the syntax for
     creating new matrices.  For example:

          HCAT = [ ARRAY1, ARRAY2, ... ]

     See also: *note cat: XREFcat, *note vertcat: XREFvertcat.

 -- : vertcat (ARRAY1, ARRAY2, ..., ARRAYN)
     Return the vertical concatenation of N-D array objects, ARRAY1,
     ARRAY2, ..., ARRAYN along dimension 1.

     Arrays may also be concatenated vertically using the syntax for
     creating new matrices.  For example:

          VCAT = [ ARRAY1; ARRAY2; ... ]

     See also: *note cat: XREFcat, *note horzcat: XREFhorzcat.

 -- : permute (A, PERM)
     Return the generalized transpose for an N-D array object A.

     The permutation vector PERM must contain the elements ‘1:ndims (A)’
     (in any order, but each element must appear only once).  The Nth
     dimension of A gets remapped to dimension ‘PERM(N)’.  For example:

          X = zeros ([2, 3, 5, 7]);
          size (X)
             ⇒  2   3   5   7

          size (permute (X, [2, 1, 3, 4]))
             ⇒  3   2   5   7

          size (permute (X, [1, 3, 4, 2]))
             ⇒  2   5   7   3

          ## The identity permutation
          size (permute (X, [1, 2, 3, 4]))
             ⇒  2   3   5   7

     See also: *note ipermute: XREFipermute.

 -- : ipermute (A, IPERM)
     The inverse of the ‘permute’ function.

     The expression

          ipermute (permute (A, perm), perm)

     returns the original array A.

     See also: *note permute: XREFpermute.

 -- : reshape (A, M, N, ...)
 -- : reshape (A, [M N ...])
 -- : reshape (A, ..., [], ...)
 -- : reshape (A, SIZE)
     Return a matrix with the specified dimensions (M, N, ...) whose
     elements are taken from the matrix A.

     The elements of the matrix are accessed in column-major order (like
     Fortran arrays are stored).

     The following code demonstrates reshaping a 1x4 row vector into a
     2x2 square matrix.

          reshape ([1, 2, 3, 4], 2, 2)
                ⇒  1  3
                    2  4

     Note that the total number of elements in the original matrix
     (‘prod (size (A))’) must match the total number of elements in the
     new matrix (‘prod ([M N ...])’).

     A single dimension of the return matrix may be left unspecified and
     Octave will determine its size automatically.  An empty matrix ([])
     is used to flag the unspecified dimension.

     See also: *note resize: XREFresize, *note vec: XREFvec, *note
     postpad: XREFpostpad, *note cat: XREFcat, *note squeeze:
     XREFsqueeze.

 -- : resize (X, M)
 -- : resize (X, M, N, ...)
 -- : resize (X, [M N ...])
     Resize X cutting off elements as necessary.

     In the result, element with certain indices is equal to the
     corresponding element of X if the indices are within the bounds of
     X; otherwise, the element is set to zero.

     In other words, the statement

          y = resize (x, dv)

     is equivalent to the following code:

          y = zeros (dv, class (x));
          sz = min (dv, size (x));
          for i = 1:length (sz)
            idx{i} = 1:sz(i);
          endfor
          y(idx{:}) = x(idx{:});

     but is performed more efficiently.

     If only M is supplied, and it is a scalar, the dimension of the
     result is M-by-M.  If M, N, ... are all scalars, then the
     dimensions of the result are M-by-N-by-....  If given a vector as
     input, then the dimensions of the result are given by the elements
     of that vector.

     An object can be resized to more dimensions than it has; in such
     case the missing dimensions are assumed to be 1.  Resizing an
     object to fewer dimensions is not possible.

     See also: *note reshape: XREFreshape, *note postpad: XREFpostpad,
     *note prepad: XREFprepad, *note cat: XREFcat.

 -- : Y = circshift (X, N)
 -- : Y = circshift (X, N, DIM)
     Circularly shift the values of the array X.

     N must be a vector of integers no longer than the number of
     dimensions in X.  The values of N can be either positive or
     negative, which determines the direction in which the values of X
     are shifted.  If an element of N is zero, then the corresponding
     dimension of X will not be shifted.

     If a scalar DIM is given then operate along the specified
     dimension.  In this case N must be a scalar as well.

     Examples:

          x = [1, 2, 3; 4, 5, 6; 7, 8, 9];
          circshift (x, 1)
          ⇒  7, 8, 9
              1, 2, 3
              4, 5, 6
          circshift (x, -2)
          ⇒  7, 8, 9
              1, 2, 3
              4, 5, 6
          circshift (x, [0,1])
          ⇒  3, 1, 2
              6, 4, 5
              9, 7, 8

     See also: *note permute: XREFpermute, *note ipermute: XREFipermute,
     *note shiftdim: XREFshiftdim.

 -- : shift (X, B)
 -- : shift (X, B, DIM)
     If X is a vector, perform a circular shift of length B of the
     elements of X.

     If X is a matrix, do the same for each column of X.

     If the optional DIM argument is given, operate along this
     dimension.

 -- : Y = shiftdim (X, N)
 -- : [Y, NS] = shiftdim (X)
     Shift the dimensions of X by N, where N must be an integer scalar.

     When N is positive, the dimensions of X are shifted to the left,
     with the leading dimensions circulated to the end.  If N is
     negative, then the dimensions of X are shifted to the right, with N
     leading singleton dimensions added.

     Called with a single argument, ‘shiftdim’, removes the leading
     singleton dimensions, returning the number of dimensions removed in
     the second output argument NS.

     For example:

          x = ones (1, 2, 3);
          size (shiftdim (x, -1))
             ⇒ [1, 1, 2, 3]
          size (shiftdim (x, 1))
             ⇒ [2, 3]
          [b, ns] = shiftdim (x)
             ⇒ b = [1, 1, 1; 1, 1, 1]
             ⇒ ns = 1

     See also: *note reshape: XREFreshape, *note permute: XREFpermute,
     *note ipermute: XREFipermute, *note circshift: XREFcircshift, *note
     squeeze: XREFsqueeze.

 -- : [S, I] = sort (X)
 -- : [S, I] = sort (X, DIM)
 -- : [S, I] = sort (X, MODE)
 -- : [S, I] = sort (X, DIM, MODE)
     Return a copy of X with the elements arranged in increasing order.

     For matrices, ‘sort’ orders the elements within columns

     For example:

          sort ([1, 2; 2, 3; 3, 1])
             ⇒  1  1
                 2  2
                 3  3

     If the optional argument DIM is given, then the matrix is sorted
     along the dimension defined by DIM.  The optional argument ‘mode’
     defines the order in which the values will be sorted.  Valid values
     of ‘mode’ are "ascend" or "descend".

     The ‘sort’ function may also be used to produce a matrix containing
     the original row indices of the elements in the sorted matrix.  For
     example:

          [s, i] = sort ([1, 2; 2, 3; 3, 1])
            ⇒ s = 1  1
                   2  2
                   3  3
            ⇒ i = 1  3
                   2  1
                   3  2

     For equal elements, the indices are such that equal elements are
     listed in the order in which they appeared in the original list.

     Sorting of complex entries is done first by magnitude (‘abs (Z)’)
     and for any ties by phase angle (‘angle (z)’).  For example:

          sort ([1+i; 1; 1-i])
              ⇒ 1 + 0i
                 1 - 1i
                 1 + 1i

     NaN values are treated as being greater than any other value and
     are sorted to the end of the list.

     The ‘sort’ function may also be used to sort strings and cell
     arrays of strings, in which case ASCII dictionary order (uppercase
     ’A’ precedes lowercase ’a’) of the strings is used.

     The algorithm used in ‘sort’ is optimized for the sorting of
     partially ordered lists.

     See also: *note sortrows: XREFsortrows, *note issorted:
     XREFissorted.

 -- : [S, I] = sortrows (A)
 -- : [S, I] = sortrows (A, C)
     Sort the rows of the matrix A according to the order of the columns
     specified in C.

     By default (C omitted, or a particular column unspecified in C) an
     ascending sort order is used.  However, if elements of C are
     negative then the corresponding column is sorted in descending
     order.  If the elements of A are strings then a lexicographical
     sort is used.

     Example: sort by column 2 in descending order, then 3 in ascending
     order

          x = [ 7, 1, 4;
                8, 3, 5;
                9, 3, 6 ];
          sortrows (x, [-2, 3])
             ⇒ 8  3  5
                9  3  6
                7  1  4

     See also: *note sort: XREFsort.

 -- : issorted (A)
 -- : issorted (A, MODE)
 -- : issorted (A, "rows", MODE)
     Return true if the array is sorted according to MODE, which may be
     either "ascending", "descending", or "either".

     By default, MODE is "ascending".  NaNs are treated in the same
     manner as ‘sort’.

     If the optional argument "rows" is supplied, check whether the
     array is sorted by rows as output by the function ‘sortrows’ (with
     no options).

     This function does not support sparse matrices.

     See also: *note sort: XREFsort, *note sortrows: XREFsortrows.

 -- : nth_element (X, N)
 -- : nth_element (X, N, DIM)
     Select the n-th smallest element of a vector, using the ordering
     defined by ‘sort’.

     The result is equivalent to ‘sort(X)(N)’.

     N can also be a contiguous range, either ascending ‘l:u’ or
     descending ‘u:-1:l’, in which case a range of elements is returned.

     If X is an array, ‘nth_element’ operates along the dimension
     defined by DIM, or the first non-singleton dimension if DIM is not
     given.

     Programming Note: nth_element encapsulates the C++ standard library
     algorithms nth_element and partial_sort.  On average, the
     complexity of the operation is O(M*log(K)), where
     ‘M = size (X, DIM)’ and ‘K = length (N)’.  This function is
     intended for cases where the ratio K/M is small; otherwise, it may
     be better to use ‘sort’.

     See also: *note sort: XREFsort, *note min: XREFmin, *note max:
     XREFmax.

 -- : A_LO = tril (A)
 -- : A_LO = tril (A, K)
 -- : A_LO = tril (A, K, PACK)
     Return a new matrix formed by extracting the lower triangular part
     of the matrix A, and setting all other elements to zero.

     The optional second argument specifies how many diagonals above or
     below the main diagonal should also be set to zero.  The default
     value of K is zero which includes the main diagonal as part of the
     result.  If the value of K is a nonzero integer then the selection
     of elements starts at an offset of K diagonals above the main
     diagonal for positive K or below the main diagonal for negative K.
     The absolute value of K may not be greater than the number of
     subdiagonals or superdiagonals.

     Example 1 : exclude main diagonal

          tril (ones (3), -1)
               ⇒  0  0  0
                   1  0  0
                   1  1  0


     Example 2 : include first superdiagonal

          tril (ones (3), 1)
               ⇒  1  1  0
                   1  1  1
                   1  1  1

     If the optional third argument "pack" is given then the extracted
     elements are not inserted into a matrix, but instead stacked
     column-wise one above another, and returned as a column vector.

     See also: *note triu: XREFtriu, *note istril: XREFistril, *note
     diag: XREFdiag.

 -- : A_UP = triu (A)
 -- : A_UP = triu (A, K)
 -- : A_UP = triu (A, K, PACK)
     Return a new matrix formed by extracting the upper triangular part
     of the matrix A, and setting all other elements to zero.

     The optional second argument specifies how many diagonals above or
     below the main diagonal should also be set to zero.  The default
     value of K is zero which includes the main diagonal as part of the
     result.  If the value of K is a nonzero integer then the selection
     of elements starts at an offset of K diagonals above the main
     diagonal for positive K or below the main diagonal for negative K.
     The absolute value of K may not be greater than the number of
     subdiagonals or superdiagonals.

     Example 1 : exclude main diagonal

          triu (ones (3), 1)
               ⇒  0  1  1
                   0  0  1
                   0  0  0


     Example 2 : include first subdiagonal

          triu (ones (3), -1)
               ⇒  1  1  1
                   1  1  1
                   0  1  1

     If the optional third argument "pack" is given then the extracted
     elements are not inserted into a matrix, but instead stacked
     column-wise one above another, and returned as a column vector.

     See also: *note tril: XREFtril, *note istriu: XREFistriu, *note
     diag: XREFdiag.

 -- : V = vec (X)
 -- : V = vec (X, DIM)
     Return the vector obtained by stacking the columns of the matrix X
     one above the other.

     Without DIM this is equivalent to ‘X(:)’.

     If DIM is supplied, the dimensions of V are set to DIM with all
     elements along the last dimension.  This is equivalent to ‘shiftdim
     (X(:), 1-DIM)’.

     See also: *note vech: XREFvech, *note resize: XREFresize, *note
     cat: XREFcat.

 -- : vech (X)
     Return the vector obtained by eliminating all superdiagonal
     elements of the square matrix X and stacking the result one column
     above the other.

     This has uses in matrix calculus where the underlying matrix is
     symmetric and it would be pointless to keep values above the main
     diagonal.

     See also: *note vec: XREFvec.

 -- : prepad (X, L)
 -- : prepad (X, L, C)
 -- : prepad (X, L, C, DIM)
     Prepend the scalar value C to the vector X until it is of length L.
     If C is not given, a value of 0 is used.

     If ‘length (X) > L’, elements from the beginning of X are removed
     until a vector of length L is obtained.

     If X is a matrix, elements are prepended or removed from each row.

     If the optional argument DIM is given, operate along this
     dimension.

     If DIM is larger than the dimensions of X, the result will have DIM
     dimensions.

     See also: *note postpad: XREFpostpad, *note cat: XREFcat, *note
     resize: XREFresize.

 -- : postpad (X, L)
 -- : postpad (X, L, C)
 -- : postpad (X, L, C, DIM)
     Append the scalar value C to the vector X until it is of length L.
     If C is not given, a value of 0 is used.

     If ‘length (X) > L’, elements from the end of X are removed until a
     vector of length L is obtained.

     If X is a matrix, elements are appended or removed from each row.

     If the optional argument DIM is given, operate along this
     dimension.

     If DIM is larger than the dimensions of X, the result will have DIM
     dimensions.

     See also: *note prepad: XREFprepad, *note cat: XREFcat, *note
     resize: XREFresize.

 -- : M = diag (V)
 -- : M = diag (V, K)
 -- : M = diag (V, M, N)
 -- : V = diag (M)
 -- : V = diag (M, K)
     Return a diagonal matrix with vector V on diagonal K.

     The second argument is optional.  If it is positive, the vector is
     placed on the K-th superdiagonal.  If it is negative, it is placed
     on the -K-th subdiagonal.  The default value of K is 0, and the
     vector is placed on the main diagonal.  For example:

          diag ([1, 2, 3], 1)
             ⇒  0  1  0  0
                 0  0  2  0
                 0  0  0  3
                 0  0  0  0

     The 3-input form returns a diagonal matrix with vector V on the
     main diagonal and the resulting matrix being of size M rows x N
     columns.

     Given a matrix argument, instead of a vector, ‘diag’ extracts the
     K-th diagonal of the matrix.

 -- : blkdiag (A, B, C, ...)
     Build a block diagonal matrix from A, B, C, ...

     All arguments must be numeric and either two-dimensional matrices
     or scalars.  If any argument is of type sparse, the output will
     also be sparse.

     See also: *note diag: XREFdiag, *note horzcat: XREFhorzcat, *note
     vertcat: XREFvertcat, *note sparse: XREFsparse.


File: octave.info,  Node: Special Utility Matrices,  Next: Famous Matrices,  Prev: Rearranging Matrices,  Up: Matrix Manipulation

16.3 Special Utility Matrices
=============================

 -- : eye (N)
 -- : eye (M, N)
 -- : eye ([M N])
 -- : eye (..., CLASS)
     Return an identity matrix.

     If invoked with a single scalar argument N, return a square NxN
     identity matrix.

     If supplied two scalar arguments (M, N), ‘eye’ takes them to be the
     number of rows and columns.  If given a vector with two elements,
     ‘eye’ uses the values of the elements as the number of rows and
     columns, respectively.  For example:

          eye (3)
           ⇒  1  0  0
               0  1  0
               0  0  1

     The following expressions all produce the same result:

          eye (2)
          ≡
          eye (2, 2)
          ≡
          eye (size ([1, 2; 3, 4]))

     The optional argument CLASS, allows ‘eye’ to return an array of the
     specified type, like

          val = zeros (n,m, "uint8")

     Calling ‘eye’ with no arguments is equivalent to calling it with an
     argument of 1.  Any negative dimensions are treated as zero.  These
     odd definitions are for compatibility with MATLAB.

     See also: *note speye: XREFspeye, *note ones: XREFones, *note
     zeros: XREFzeros.

 -- : ones (N)
 -- : ones (M, N)
 -- : ones (M, N, K, ...)
 -- : ones ([M N ...])
 -- : ones (..., CLASS)
     Return a matrix or N-dimensional array whose elements are all 1.

     If invoked with a single scalar integer argument N, return a square
     NxN matrix.

     If invoked with two or more scalar integer arguments, or a vector
     of integer values, return an array with the given dimensions.

     To create a constant matrix whose values are all the same use an
     expression such as

          val_matrix = val * ones (m, n)

     The optional argument CLASS specifies the class of the return array
     and defaults to double.  For example:

          val = ones (m,n, "uint8")

     See also: *note zeros: XREFzeros.

 -- : zeros (N)
 -- : zeros (M, N)
 -- : zeros (M, N, K, ...)
 -- : zeros ([M N ...])
 -- : zeros (..., CLASS)
     Return a matrix or N-dimensional array whose elements are all 0.

     If invoked with a single scalar integer argument, return a square
     NxN matrix.

     If invoked with two or more scalar integer arguments, or a vector
     of integer values, return an array with the given dimensions.

     The optional argument CLASS specifies the class of the return array
     and defaults to double.  For example:

          val = zeros (m,n, "uint8")

     See also: *note ones: XREFones.

 -- : repmat (A, M)
 -- : repmat (A, M, N)
 -- : repmat (A, M, N, P ...)
 -- : repmat (A, [M N])
 -- : repmat (A, [M N P ...])
     Repeat matrix or N-D array.

     Form a block matrix of size M by N, with a copy of matrix A as each
     element.

     If N is not specified, form an M by M block matrix.  For copying
     along more than two dimensions, specify the number of times to copy
     across each dimension M, N, P, ..., in a vector in the second
     argument.

     See also: *note bsxfun: XREFbsxfun, *note kron: XREFkron, *note
     repelems: XREFrepelems.

 -- : repelems (X, R)
     Construct a vector of repeated elements from X.

     R is a 2xN integer matrix specifying which elements to repeat and
     how often to repeat each element.  Entries in the first row,
     R(1,j), select an element to repeat.  The corresponding entry in
     the second row, R(2,j), specifies the repeat count.  If X is a
     matrix then the columns of X are imagined to be stacked on top of
     each other for purposes of the selection index.  A row vector is
     always returned.

     Conceptually the result is calculated as follows:

          y = [];
          for i = 1:columns (R)
            y = [y, X(R(1,i)*ones(1, R(2,i)))];
          endfor

     See also: *note repmat: XREFrepmat, *note cat: XREFcat.

 -- : XXX = repelem (X, R)
 -- : XXX = repelem (X, R_1, ..., R_N)
     Construct an array of repeated elements from X and repeat
     instructions R_1, ....

     X must be a scalar, vector, or N-dimensional array.

     A repeat instruction R_J must either be a scalar or a vector.  If
     the instruction is a scalar then each component of X in dimension J
     is repeated R_J times.  If the instruction is a vector then it must
     have the same number of elements as the corresponding dimension J
     of X.  In this case, the Kth component of dimension J is repeated
     ‘R_J(K)’ times.

     If X is a scalar or vector then ‘repelem’ may be called with just a
     single repeat instruction R and ‘repelem’ will return a vector with
     the same orientation as the input.

     If X is a matrix then at least two R_Js must be specified.

     Note: Using ‘repelem’ with a vector X and a vector for R_J is
     equivalent to Run Length Decoding.

     Examples:

          A = [1 2 3 4 5];
          B = [2 1 0 1 2];
          repelem (A, B)
            ⇒   1   1   2   4   5   5

          A = magic (3)
            ⇒   8   1   6
                 3   5   7
                 4   9   2
          B1 = [1 2 3];
          B2 = 2;
          repelem (A, B1, B2)
            ⇒     8   8   1   1   6   6
                   3   3   5   5   7   7
                   3   3   5   5   7   7
                   4   4   9   9   2   2
                   4   4   9   9   2   2
                   4   4   9   9   2   2

     More R_J may be specified than the number of dimensions of X.  Any
     excess R_J must be scalars (because X’s size in those dimensions is
     only 1), and X will be replicated in those dimensions accordingly.

          A = [1 2 3 4 5];
          B1 = 2;
          B2 = [2 1 3 0 2];
          B3 = 3;
          repelem (A, B1, B2, B3)
            ⇒    ans(:,:,1) =
                     1   1   2   3   3   3   5   5
                     1   1   2   3   3   3   5   5

                  ans(:,:,2) =

                     1   1   2   3   3   3   5   5
                     1   1   2   3   3   3   5   5

                  ans(:,:,3) =
                     1   1   2   3   3   3   5   5
                     1   1   2   3   3   3   5   5

     R_J must be specified in order.  A placeholder of 1 may be used for
     dimensions which do not need replication.

          repelem ([-1, 0; 0, 1], 1, 2, 1, 2)
            ⇒  ans(:,:,1,1) =
                  -1  -1   0   0
                   0   0   1   1

                ans(:,:,1,2) =
                  -1  -1   0   0
                   0   0   1   1

     If fewer R_J are given than the number of dimensions in X,
     ‘repelem’ will assume R_J is 1 for those dimensions.

          A = cat (3, [-1 0; 0 1], [-1 0; 0 1])
            ⇒  ans(:,:,1) =
                  -1   0
                   0   1

                ans(:,:,2) =
                  -1   0
                   0   1

          repelem (A,2,3)
            ⇒  ans(:,:,1) =
                  -1  -1  -1   0   0   0
                  -1  -1  -1   0   0   0
                   0   0   0   1   1   1
                   0   0   0   1   1   1

                ans(:,:,2) =
                  -1  -1  -1   0   0   0
                  -1  -1  -1   0   0   0
                   0   0   0   1   1   1
                   0   0   0   1   1   1

     ‘repelem’ preserves the class of X, and works with strings, cell
     arrays, NA, and NAN inputs.  If any R_J is 0 the output will be an
     empty array.

          repelem ("Octave", 2, 3)
            ⇒    OOOccctttaaavvveee
                  OOOccctttaaavvveee

          repelem ([1 2 3; 1 2 3], 2, 0)
            ⇒    [](4x0)

     See also: *note cat: XREFcat, *note kron: XREFkron, *note repmat:
     XREFrepmat.

   The functions ‘linspace’ and ‘logspace’ make it very easy to create
vectors with evenly or logarithmically spaced elements.  *Note Ranges::.

 -- : linspace (START, END)
 -- : linspace (START, END, N)
     Return a row vector with N linearly spaced elements between START
     and END.

     If the number of elements is greater than one, then the endpoints
     START and END are always included in the range.  If START is
     greater than END, the elements are stored in decreasing order.  If
     the number of points is not specified, a value of 100 is used.

     The ‘linspace’ function returns a row vector when both START and
     END are scalars.  If one, or both, inputs are vectors, then
     ‘linspace’ transforms them to column vectors and returns a matrix
     where each row is an independent sequence between
     ‘START(ROW_N), END(ROW_N)’.

     For compatibility with MATLAB, return the second argument (END)
     when only a single value (N = 1) is requested.

     See also: *note colon: XREFcolon, *note logspace: XREFlogspace.

 -- : logspace (A, B)
 -- : logspace (A, B, N)
 -- : logspace (A, pi, N)
     Return a row vector with N elements logarithmically spaced from
     10^A to 10^B.

     If N is unspecified it defaults to 50.

     If B is equal to pi, the points are between 10^A and pi, _not_ 10^A
     and 10^pi, in order to be compatible with the corresponding MATLAB
     function.

     Also for compatibility with MATLAB, return the right-hand side of
     the range (10^B) when just a single value is requested.

     See also: *note linspace: XREFlinspace.

 -- : rand (N)
 -- : rand (M, N, ...)
 -- : rand ([M N ...])
 -- : V = rand ("state")
 -- : rand ("state", V)
 -- : rand ("state", "reset")
 -- : V = rand ("seed")
 -- : rand ("seed", V)
 -- : rand ("seed", "reset")
 -- : rand (..., "single")
 -- : rand (..., "double")
     Return a matrix with random elements uniformly distributed on the
     interval (0, 1).

     The arguments are handled the same as the arguments for ‘eye’.

     You can query the state of the random number generator using the
     form

          v = rand ("state")

     This returns a column vector V of length 625.  Later, you can
     restore the random number generator to the state V using the form

          rand ("state", v)

     You may also initialize the state vector from an arbitrary vector
     of length ≤ 625 for V.  This new state will be a hash based on the
     value of V, not V itself.

     By default, the generator is initialized from ‘/dev/urandom’ if it
     is available, otherwise from CPU time, wall clock time, and the
     current fraction of a second.  Note that this differs from MATLAB,
     which always initializes the state to the same state at startup.
     To obtain behavior comparable to MATLAB, initialize with a
     deterministic state vector in Octave’s startup files (*note Startup
     Files::).

     To compute the pseudo-random sequence, ‘rand’ uses the Mersenne
     Twister with a period of 2^{19937}-1 (See M. Matsumoto and T.
     Nishimura, ‘Mersenne Twister: A 623-dimensionally equidistributed
     uniform pseudorandom number generator’, ACM Trans.  on Modeling and
     Computer Simulation Vol.  8, No.  1, pp.  3–30, January 1998,
     <http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html>).  Do
     *not* use for cryptography without securely hashing several
     returned values together, otherwise the generator state can be
     learned after reading 624 consecutive values.

     Older versions of Octave used a different random number generator.
     The new generator is used by default as it is significantly faster
     than the old generator, and produces random numbers with a
     significantly longer cycle time.  However, in some circumstances it
     might be desirable to obtain the same random sequences as produced
     by the old generators.  To do this the keyword "seed" is used to
     specify that the old generators should be used, as in

          rand ("seed", val)

     which sets the seed of the generator to VAL.  The seed of the
     generator can be queried with

          s = rand ("seed")

     However, it should be noted that querying the seed will not cause
     ‘rand’ to use the old generators, only setting the seed will.  To
     cause ‘rand’ to once again use the new generators, the keyword
     "state" should be used to reset the state of the ‘rand’.

     The state or seed of the generator can be reset to a new random
     value using the "reset" keyword.

     The class of the value returned can be controlled by a trailing
     "double" or "single" argument.  These are the only valid classes.

     See also: *note randn: XREFrandn, *note rande: XREFrande, *note
     randg: XREFrandg, *note randp: XREFrandp.

 -- : randi (IMAX)
 -- : randi (IMAX, N)
 -- : randi (IMAX, M, N, ...)
 -- : randi ([IMIN IMAX], ...)
 -- : randi (..., "CLASS")
     Return random integers in the range 1:IMAX.

     Additional arguments determine the shape of the return matrix.
     When no arguments are specified a single random integer is
     returned.  If one argument N is specified then a square matrix
     (N x N) is returned.  Two or more arguments will return a
     multi-dimensional matrix (M x N x ...).

     The integer range may optionally be described by a two element
     matrix with a lower and upper bound in which case the returned
     integers will be on the interval [IMIN, IMAX].

     The optional argument CLASS will return a matrix of the requested
     type.  The default is "double".

     The following example returns 150 integers in the range 1–10.

          ri = randi (10, 150, 1)

     Implementation Note: ‘randi’ relies internally on ‘rand’ which uses
     class "double" to represent numbers.  This limits the maximum
     integer (IMAX) and range (IMAX - IMIN) to the value returned by the
     ‘flintmax’ function.  For IEEE floating point numbers this value is
     2^{53} - 1.

     See also: *note rand: XREFrand.

 -- : randn (N)
 -- : randn (M, N, ...)
 -- : randn ([M N ...])
 -- : V = randn ("state")
 -- : randn ("state", V)
 -- : randn ("state", "reset")
 -- : V = randn ("seed")
 -- : randn ("seed", V)
 -- : randn ("seed", "reset")
 -- : randn (..., "single")
 -- : randn (..., "double")
     Return a matrix with normally distributed random elements having
     zero mean and variance one.

     The arguments are handled the same as the arguments for ‘rand’.

     By default, ‘randn’ uses the Marsaglia and Tsang “Ziggurat
     technique” to transform from a uniform to a normal distribution.

     The class of the value returned can be controlled by a trailing
     "double" or "single" argument.  These are the only valid classes.

     Reference: G. Marsaglia and W.W. Tsang, ‘Ziggurat Method for
     Generating Random Variables’, J. Statistical Software, vol 5, 2000,
     <https://www.jstatsoft.org/v05/i08/>

     See also: *note rand: XREFrand, *note rande: XREFrande, *note
     randg: XREFrandg, *note randp: XREFrandp.

 -- : rande (N)
 -- : rande (M, N, ...)
 -- : rande ([M N ...])
 -- : V = rande ("state")
 -- : rande ("state", V)
 -- : rande ("state", "reset")
 -- : V = rande ("seed")
 -- : rande ("seed", V)
 -- : rande ("seed", "reset")
 -- : rande (..., "single")
 -- : rande (..., "double")
     Return a matrix with exponentially distributed random elements.

     The arguments are handled the same as the arguments for ‘rand’.

     By default, ‘rande’ uses the Marsaglia and Tsang “Ziggurat
     technique” to transform from a uniform to an exponential
     distribution.

     The class of the value returned can be controlled by a trailing
     "double" or "single" argument.  These are the only valid classes.

     Reference: G. Marsaglia and W.W. Tsang, ‘Ziggurat Method for
     Generating Random Variables’, J. Statistical Software, vol 5, 2000,
     <https://www.jstatsoft.org/v05/i08/>

     See also: *note rand: XREFrand, *note randn: XREFrandn, *note
     randg: XREFrandg, *note randp: XREFrandp.

 -- : randp (L, N)
 -- : randp (L, M, N, ...)
 -- : randp (L, [M N ...])
 -- : V = randp ("state")
 -- : randp ("state", V)
 -- : randp ("state", "reset")
 -- : V = randp ("seed")
 -- : randp ("seed", V)
 -- : randp ("seed", "reset")
 -- : randp (..., "single")
 -- : randp (..., "double")
     Return a matrix with Poisson distributed random elements with mean
     value parameter given by the first argument, L.

     The arguments are handled the same as the arguments for ‘rand’,
     except for the argument L.

     Five different algorithms are used depending on the range of L and
     whether or not L is a scalar or a matrix.

     For scalar L ≤ 12, use direct method.
          W.H. Press, et al., ‘Numerical Recipes in C’, Cambridge
          University Press, 1992.

     For scalar L > 12, use rejection method.[1]
          W.H. Press, et al., ‘Numerical Recipes in C’, Cambridge
          University Press, 1992.

     For matrix L ≤ 10, use inversion method.[2]
          E. Stadlober, et al., WinRand source code, available via FTP.

     For matrix L > 10, use patchwork rejection method.
          E. Stadlober, et al., WinRand source code, available via FTP,
          or H. Zechner, ‘Efficient sampling from continuous and
          discrete unimodal distributions’, Doctoral Dissertation,
          156pp., Technical University Graz, Austria, 1994.

     For L > 1e8, use normal approximation.
          L. Montanet, et al., ‘Review of Particle Properties’, Physical
          Review D 50 p1284, 1994.

     The class of the value returned can be controlled by a trailing
     "double" or "single" argument.  These are the only valid classes.

     See also: *note rand: XREFrand, *note randn: XREFrandn, *note
     rande: XREFrande, *note randg: XREFrandg.

 -- : randg (A, N)
 -- : randg (A, M, N, ...)
 -- : randg (A, [M N ...])
 -- : V = randg ("state")
 -- : randg ("state", V)
 -- : randg ("state", "reset")
 -- : V = randg ("seed")
 -- : randg ("seed", V)
 -- : randg ("seed", "reset")
 -- : randg (..., "single")
 -- : randg (..., "double")

     Return a matrix with ‘gamma (A,1)’ distributed random elements.

     The arguments are handled the same as the arguments for ‘rand’,
     except for the argument A.

     This can be used to generate many distributions:

     ‘gamma (a, b)’ for ‘a > -1’, ‘b > 0’

               r = b * randg (a)

     ‘beta (a, b)’ for ‘a > -1’, ‘b > -1’

               r1 = randg (a, 1)
               r = r1 / (r1 + randg (b, 1))

     ‘Erlang (a, n)’

               r = a * randg (n)

     ‘chisq (df)’ for ‘df > 0’

               r = 2 * randg (df / 2)

     ‘t (df)’ for ‘0 < df < inf’ (use randn if df is infinite)

               r = randn () / sqrt (2 * randg (df / 2) / df)

     ‘F (n1, n2)’ for ‘0 < n1’, ‘0 < n2’

               ## r1 equals 1 if n1 is infinite
               r1 = 2 * randg (n1 / 2) / n1
               ## r2 equals 1 if n2 is infinite
               r2 = 2 * randg (n2 / 2) / n2
               r = r1 / r2

     negative ‘binomial (n, p)’ for ‘n > 0’, ‘0 < p <= 1’

               r = randp ((1 - p) / p * randg (n))

     non-central ‘chisq (df, L)’, for ‘df >= 0’ and ‘L > 0’
          (use chisq if ‘L = 0’)

               r = randp (L / 2)
               r(r > 0) = 2 * randg (r(r > 0))
               r(df > 0) += 2 * randg (df(df > 0)/2)

     ‘Dirichlet (a1, ... ak)’

               r = (randg (a1), ..., randg (ak))
               r = r / sum (r)

     The class of the value returned can be controlled by a trailing
     "double" or "single" argument.  These are the only valid classes.

     See also: *note rand: XREFrand, *note randn: XREFrandn, *note
     rande: XREFrande, *note randp: XREFrandp.

   The generators operate in the new or old style together, it is not
possible to mix the two.  Initializing any generator with "state" or
"seed" causes the others to switch to the same style for future calls.

   The state of each generator is independent and calls to different
generators can be interleaved without affecting the final result.  For
example,

     rand ("state", [11, 22, 33]);
     randn ("state", [44, 55, 66]);
     u = rand (100, 1);
     n = randn (100, 1);

and

     rand ("state", [11, 22, 33]);
     randn ("state", [44, 55, 66]);
     u = zeros (100, 1);
     n = zeros (100, 1);
     for i = 1:100
       u(i) = rand ();
       n(i) = randn ();
     end

produce equivalent results.  When the generators are initialized in the
old style with "seed" only ‘rand’ and ‘randn’ are independent, because
the old ‘rande’, ‘randg’ and ‘randp’ generators make calls to ‘rand’ and
‘randn’.

   The generators are initialized with random states at start-up, so
that the sequences of random numbers are not the same each time you run
Octave.(1)  If you really do need to reproduce a sequence of numbers
exactly, you can set the state or seed to a specific value.

   If invoked without arguments, ‘rand’ and ‘randn’ return a single
element of a random sequence.

   The original ‘rand’ and ‘randn’ functions use Fortran code from
RANLIB, a library of Fortran routines for random number generation,
compiled by Barry W. Brown and James Lovato of the Department of
Biomathematics at The University of Texas, M.D. Anderson Cancer Center,
Houston, TX 77030.

 -- : randperm (N)
 -- : randperm (N, M)
     Return a row vector containing a random permutation of ‘1:N’.

     If M is supplied, return M unique entries, sampled without
     replacement from ‘1:N’.

     The complexity is O(N) in memory and O(M) in time, unless M < N/5,
     in which case O(M) memory is used as well.  The randomization is
     performed using rand().  All permutations are equally likely.

     See also: *note perms: XREFperms.

   ---------- Footnotes ----------

   (1) The old versions of ‘rand’ and ‘randn’ obtain their initial seeds
from the system clock.


File: octave.info,  Node: Famous Matrices,  Prev: Special Utility Matrices,  Up: Matrix Manipulation

16.4 Famous Matrices
====================

The following functions return famous matrix forms.

 -- : gallery (NAME)
 -- : gallery (NAME, ARGS)
     Create interesting matrices for testing.

 -- : C = gallery ("cauchy", X)
 -- : C = gallery ("cauchy", X, Y)
     Create a Cauchy matrix.

 -- : C = gallery ("chebspec", N)
 -- : C = gallery ("chebspec", N, K)
     Create a Chebyshev spectral differentiation matrix.

 -- : C = gallery ("chebvand", P)
 -- : C = gallery ("chebvand", M, P)
     Create a Vandermonde-like matrix for the Chebyshev polynomials.

 -- : A = gallery ("chow", N)
 -- : A = gallery ("chow", N, ALPHA)
 -- : A = gallery ("chow", N, ALPHA, DELTA)
     Create a Chow matrix – a singular Toeplitz lower Hessenberg matrix.

 -- : C = gallery ("circul", V)
     Create a circulant matrix.

 -- : A = gallery ("clement", N)
 -- : A = gallery ("clement", N, K)
     Create a tridiagonal matrix with zero diagonal entries.

 -- : C = gallery ("compar", A)
 -- : C = gallery ("compar", A, K)
     Create a comparison matrix.

 -- : A = gallery ("condex", N)
 -- : A = gallery ("condex", N, K)
 -- : A = gallery ("condex", N, K, THETA)
     Create a ‘counterexample’ matrix to a condition estimator.

 -- : A = gallery ("cycol", [M N])
 -- : A = gallery ("cycol", N)
 -- : A = gallery (..., K)
     Create a matrix whose columns repeat cyclically.

 -- : [C, D, E] = gallery ("dorr", N)
 -- : [C, D, E] = gallery ("dorr", N, THETA)
 -- : A = gallery ("dorr", ...)
     Create a diagonally dominant, ill-conditioned, tridiagonal matrix.

 -- : A = gallery ("dramadah", N)
 -- : A = gallery ("dramadah", N, K)
     Create a (0, 1) matrix whose inverse has large integer entries.

 -- : A = gallery ("fiedler", C)
     Create a symmetric Fiedler matrix.

 -- : A = gallery ("forsythe", N)
 -- : A = gallery ("forsythe", N, ALPHA)
 -- : A = gallery ("forsythe", N, ALPHA, LAMBDA)
     Create a Forsythe matrix (a perturbed Jordan block).

 -- : F = gallery ("frank", N)
 -- : F = gallery ("frank", N, K)
     Create a Frank matrix (ill-conditioned eigenvalues).

 -- : C = gallery ("gcdmat", N)
     Create a greatest common divisor matrix.

     C is an N-by-N matrix whose values correspond to the greatest
     common divisor of its coordinate values, i.e., C(i,j) correspond
     ‘gcd (i, j)’.

 -- : A = gallery ("gearmat", N)
 -- : A = gallery ("gearmat", N, I)
 -- : A = gallery ("gearmat", N, I, J)
     Create a Gear matrix.

 -- : G = gallery ("grcar", N)
 -- : G = gallery ("grcar", N, K)
     Create a Toeplitz matrix with sensitive eigenvalues.

 -- : A = gallery ("hanowa", N)
 -- : A = gallery ("hanowa", N, D)
     Create a matrix whose eigenvalues lie on a vertical line in the
     complex plane.

 -- : V = gallery ("house", X)
 -- : [V, BETA] = gallery ("house", X)
     Create a householder matrix.

 -- : A = gallery ("integerdata", IMAX, [M N ...], J)
 -- : A = gallery ("integerdata", IMAX, M, N, ..., J)
 -- : A = gallery ("integerdata", [IMIN, IMAX], [M N ...], J)
 -- : A = gallery ("integerdata", [IMIN, IMAX], M, N, ..., J)
 -- : A = gallery ("integerdata", ..., "CLASS")
     Create a matrix with random integers in the range [1, IMAX].  If
     IMIN is given then the integers are in the range [IMIN, IMAX].

     The second input is a matrix of dimensions describing the size of
     the output.  The dimensions can also be input as comma-separated
     arguments.

     The input J is an integer index in the range [0, 2^32-1].  The
     values of the output matrix are always exactly the same
     (reproducibility) for a given size input and J index.

     The final optional argument determines the class of the resulting
     matrix.  Possible values for CLASS: "uint8", "uint16", "uint32",
     "int8", "int16", int32", "single", "double".  The default is
     "double".

 -- : A = gallery ("invhess", X)
 -- : A = gallery ("invhess", X, Y)
     Create the inverse of an upper Hessenberg matrix.

 -- : A = gallery ("invol", N)
     Create an involutory matrix.

 -- : A = gallery ("ipjfact", N)
 -- : A = gallery ("ipjfact", N, K)
     Create a Hankel matrix with factorial elements.

 -- : A = gallery ("jordbloc", N)
 -- : A = gallery ("jordbloc", N, LAMBDA)
     Create a Jordan block.

 -- : U = gallery ("kahan", N)
 -- : U = gallery ("kahan", N, THETA)
 -- : U = gallery ("kahan", N, THETA, PERT)
     Create a Kahan matrix (upper trapezoidal).

 -- : A = gallery ("kms", N)
 -- : A = gallery ("kms", N, RHO)
     Create a Kac-Murdock-Szego Toeplitz matrix.

 -- : B = gallery ("krylov", A)
 -- : B = gallery ("krylov", A, X)
 -- : B = gallery ("krylov", A, X, J)
     Create a Krylov matrix.

 -- : A = gallery ("lauchli", N)
 -- : A = gallery ("lauchli", N, MU)
     Create a Lauchli matrix (rectangular).

 -- : A = gallery ("lehmer", N)
     Create a Lehmer matrix (symmetric positive definite).

 -- : T = gallery ("lesp", N)
     Create a tridiagonal matrix with real, sensitive eigenvalues.

 -- : A = gallery ("lotkin", N)
     Create a Lotkin matrix.

 -- : A = gallery ("minij", N)
     Create a symmetric positive definite matrix MIN(i,j).

 -- : A = gallery ("moler", N)
 -- : A = gallery ("moler", N, ALPHA)
     Create a Moler matrix (symmetric positive definite).

 -- : [A, T] = gallery ("neumann", N)
     Create a singular matrix from the discrete Neumann problem
     (sparse).

 -- : A = gallery ("normaldata", [M N ...], J)
 -- : A = gallery ("normaldata", M, N, ..., J)
 -- : A = gallery ("normaldata", ..., "CLASS")
     Create a matrix with random samples from the standard normal
     distribution (mean = 0, std = 1).

     The first input is a matrix of dimensions describing the size of
     the output.  The dimensions can also be input as comma-separated
     arguments.

     The input J is an integer index in the range [0, 2^32-1].  The
     values of the output matrix are always exactly the same
     (reproducibility) for a given size input and J index.

     The final optional argument determines the class of the resulting
     matrix.  Possible values for CLASS: "single", "double".  The
     default is "double".

 -- : Q = gallery ("orthog", N)
 -- : Q = gallery ("orthog", N, K)
     Create orthogonal and nearly orthogonal matrices.

 -- : A = gallery ("parter", N)
     Create a Parter matrix (a Toeplitz matrix with singular values near
     pi).

 -- : P = gallery ("pei", N)
 -- : P = gallery ("pei", N, ALPHA)
     Create a Pei matrix.

 -- : A = gallery ("Poisson", N)
     Create a block tridiagonal matrix from Poisson’s equation (sparse).

 -- : A = gallery ("prolate", N)
 -- : A = gallery ("prolate", N, W)
     Create a prolate matrix (symmetric, ill-conditioned Toeplitz
     matrix).

 -- : H = gallery ("randhess", X)
     Create a random, orthogonal upper Hessenberg matrix.

 -- : A = gallery ("rando", N)
 -- : A = gallery ("rando", N, K)
     Create a random matrix with elements -1, 0 or 1.

 -- : A = gallery ("randsvd", N)
 -- : A = gallery ("randsvd", N, KAPPA)
 -- : A = gallery ("randsvd", N, KAPPA, MODE)
 -- : A = gallery ("randsvd", N, KAPPA, MODE, KL)
 -- : A = gallery ("randsvd", N, KAPPA, MODE, KL, KU)
     Create a random matrix with pre-assigned singular values.

 -- : A = gallery ("redheff", N)
     Create a zero and ones matrix of Redheffer associated with the
     Riemann hypothesis.

 -- : A = gallery ("riemann", N)
     Create a matrix associated with the Riemann hypothesis.

 -- : A = gallery ("ris", N)
     Create a symmetric Hankel matrix.

 -- : A = gallery ("smoke", N)
 -- : A = gallery ("smoke", N, K)
     Create a complex matrix, with a ‘smoke ring’ pseudospectrum.

 -- : T = gallery ("toeppd", N)
 -- : T = gallery ("toeppd", N, M)
 -- : T = gallery ("toeppd", N, M, W)
 -- : T = gallery ("toeppd", N, M, W, THETA)
     Create a symmetric positive definite Toeplitz matrix.

 -- : P = gallery ("toeppen", N)
 -- : P = gallery ("toeppen", N, A)
 -- : P = gallery ("toeppen", N, A, B)
 -- : P = gallery ("toeppen", N, A, B, C)
 -- : P = gallery ("toeppen", N, A, B, C, D)
 -- : P = gallery ("toeppen", N, A, B, C, D, E)
     Create a pentadiagonal Toeplitz matrix (sparse).

 -- : A = gallery ("tridiag", X, Y, Z)
 -- : A = gallery ("tridiag", N)
 -- : A = gallery ("tridiag", N, C, D, E)
     Create a tridiagonal matrix (sparse).

 -- : T = gallery ("triw", N)
 -- : T = gallery ("triw", N, ALPHA)
 -- : T = gallery ("triw", N, ALPHA, K)
     Create an upper triangular matrix discussed by Kahan, Golub, and
     Wilkinson.

 -- : A = gallery ("uniformdata", [M N ...], J)
 -- : A = gallery ("uniformdata", M, N, ..., J)
 -- : A = gallery ("uniformdata", ..., "CLASS")
     Create a matrix with random samples from the standard uniform
     distribution (range [0,1]).

     The first input is a matrix of dimensions describing the size of
     the output.  The dimensions can also be input as comma-separated
     arguments.

     The input J is an integer index in the range [0, 2^32-1].  The
     values of the output matrix are always exactly the same
     (reproducibility) for a given size input and J index.

     The final optional argument determines the class of the resulting
     matrix.  Possible values for CLASS: "single", "double".  The
     default is "double".

 -- : A = gallery ("wathen", NX, NY)
 -- : A = gallery ("wathen", NX, NY, K)
     Create the Wathen matrix.

 -- : [A, B] = gallery ("wilk", N)
     Create various specific matrices devised/discussed by Wilkinson.

 -- : hadamard (N)
     Construct a Hadamard matrix (Hn) of size N-by-N.

     The size N must be of the form 2^k * p in which p is one of 1, 12,
     20 or 28.  The returned matrix is normalized, meaning
     ‘Hn(:,1) == 1’ and ‘Hn(1,:) == 1’.

     Some of the properties of Hadamard matrices are:

        • ‘kron (Hm, Hn)’ is a Hadamard matrix of size M-by-N.

        • ‘Hn * Hn' = N * eye (N)’.

        • The rows of Hn are orthogonal.

        • ‘det (A) <= abs (det (Hn))’ for all A with
          ‘abs (A(i, j)) <= 1’.

        • Multiplying any row or column by -1 and the matrix will remain
          a Hadamard matrix.

     See also: *note compan: XREFcompan, *note hankel: XREFhankel, *note
     toeplitz: XREFtoeplitz.

 -- : hankel (C)
 -- : hankel (C, R)
     Return the Hankel matrix constructed from the first column C, and
     (optionally) the last row R.

     If the last element of C is not the same as the first element of R,
     the last element of C is used.  If the second argument is omitted,
     it is assumed to be a vector of zeros with the same size as C.

     A Hankel matrix formed from an m-vector C, and an n-vector R, has
     the elements

          H(i,j) = c(i+j-1),  i+j-1 <= m;
          H(i,j) = r(i+j-m),  otherwise

     See also: *note hadamard: XREFhadamard, *note toeplitz:
     XREFtoeplitz.

 -- : hilb (N)
     Return the Hilbert matrix of order N.

     The i,j element of a Hilbert matrix is defined as

          H(i, j) = 1 / (i + j - 1)

     Hilbert matrices are close to being singular which make them
     difficult to invert with numerical routines.  Comparing the
     condition number of a random matrix 5x5 matrix with that of a
     Hilbert matrix of order 5 reveals just how difficult the problem
     is.

          cond (rand (5))
             ⇒ 14.392
          cond (hilb (5))
             ⇒ 4.7661e+05

     See also: *note invhilb: XREFinvhilb.

 -- : invhilb (N)
     Return the inverse of the Hilbert matrix of order N.

     This can be computed exactly using


                     (i+j)         /n+i-1\  /n+j-1\   /i+j-2\ 2
          A(i,j) = -1      (i+j-1)(       )(       ) (       )
                                   \ n-j /  \ n-i /   \ i-2 /

                 = p(i) p(j) / (i+j-1)


     where

                   k  /k+n-1\   /n\
          p(k) = -1  (       ) (   )
                      \ k-1 /   \k/

     The validity of this formula can easily be checked by expanding the
     binomial coefficients in both formulas as factorials.  It can be
     derived more directly via the theory of Cauchy matrices.  See J. W.
     Demmel, ‘Applied Numerical Linear Algebra’, p.  92.

     Compare this with the numerical calculation of ‘inverse (hilb
     (n))’, which suffers from the ill-conditioning of the Hilbert
     matrix, and the finite precision of your computer’s floating point
     arithmetic.

     See also: *note hilb: XREFhilb.

 -- : magic (N)

     Create an N-by-N magic square.

     A magic square is an arrangement of the integers ‘1:n^2’ such that
     the row sums, column sums, and diagonal sums are all equal to the
     same value.

     Note: N must be a scalar greater than or equal to 3.  If you supply
     N less than 3, magic returns either a nonmagic square, or else the
     degenerate magic squares 1 and [].

 -- : pascal (N)
 -- : pascal (N, T)
     Return the Pascal matrix of order N if ‘T = 0’.

     The default value of T is 0.

     When ‘T = 1’, return the pseudo-lower triangular Cholesky factor of
     the Pascal matrix (The sign of some columns may be negative).  This
     matrix is its own inverse, that is ‘pascal (N, 1) ^ 2 == eye (N)’.

     If ‘T = -1’, return the true Cholesky factor with strictly positive
     values on the diagonal.

     If ‘T = 2’, return a transposed and permuted version of ‘pascal (N,
     1)’, which is the cube root of the identity matrix.  That is,
     ‘pascal (N, 2) ^ 3 == eye (N)’.

     See also: *note chol: XREFchol.

 -- : rosser ()
     Return the Rosser matrix.

     This is a difficult test case used to evaluate eigenvalue
     algorithms.

     See also: *note wilkinson: XREFwilkinson, *note eig: XREFeig.

 -- : toeplitz (C)
 -- : toeplitz (C, R)
     Return the Toeplitz matrix constructed from the first column C, and
     optionally the first row R.

     If the second argument is omitted, the first row is taken to be the
     same as the first column.  If the first element of R is not the
     same as the first element of C, the first element of C is used.

     A Toeplitz, or diagonal-constant, matrix has the same value along
     each diagonal.  Although it need not be square, it often is.  An
     MxN Toeplitz matrix has the form:

          c(1)  r(2)   r(3)  ...  r(n)
          c(2)  c(1)   r(2)  ... r(n-1)
          c(3)  c(2)   c(1)  ... r(n-2)
           .     .      .   .      .
           .     .      .     .    .
           .     .      .       .  .
          c(m) c(m-1) c(m-2) ... c(m-n+1)

     See also: *note hankel: XREFhankel.

 -- : vander (C)
 -- : vander (C, N)
     Return the Vandermonde matrix whose next to last column is C.

     If N is specified, it determines the number of columns; otherwise,
     N is taken to be equal to the length of C.

     A Vandermonde matrix has the form:

          c(1)^(n-1) ... c(1)^2  c(1)  1
          c(2)^(n-1) ... c(2)^2  c(2)  1
              .     .      .      .    .
              .       .    .      .    .
              .         .  .      .    .
          c(n)^(n-1) ... c(n)^2  c(n)  1

     See also: *note polyfit: XREFpolyfit.

 -- : wilkinson (N)
     Return the Wilkinson matrix of order N.

     Wilkinson matrices are symmetric and tridiagonal with pairs of
     nearly, but not exactly, equal eigenvalues.  They are useful in
     testing the behavior and performance of eigenvalue solvers.

     See also: *note rosser: XREFrosser, *note eig: XREFeig.


File: octave.info,  Node: Arithmetic,  Next: Linear Algebra,  Prev: Matrix Manipulation,  Up: Top

17 Arithmetic
*************

Unless otherwise noted, all of the functions described in this chapter
will work for real and complex scalar, vector, or matrix arguments.
Functions described as “mapping functions” apply the given operation
individually to each element when given a matrix argument.  For example:

     sin ([1, 2; 3, 4])
          ⇒  0.84147   0.90930
              0.14112  -0.75680

* Menu:

* Exponents and Logarithms::
* Complex Arithmetic::
* Trigonometry::
* Sums and Products::
* Utility Functions::
* Special Functions::
* Rational Approximations::
* Coordinate Transformations::
* Mathematical Constants::


File: octave.info,  Node: Exponents and Logarithms,  Next: Complex Arithmetic,  Up: Arithmetic

17.1 Exponents and Logarithms
=============================

 -- : exp (X)
     Compute ‘e^x’ for each element of X.

     To compute the matrix exponential, see *note Linear Algebra::.

     See also: *note log: XREFlog.

 -- : expm1 (X)
     Compute ‘exp (X) - 1’ accurately in the neighborhood of zero.

     See also: *note exp: XREFexp.

 -- : log (X)
     Compute the natural logarithm, ‘ln (X)’, for each element of X.

     To compute the matrix logarithm, see *note Linear Algebra::.

     See also: *note exp: XREFexp, *note log1p: XREFlog1p, *note log2:
     XREFlog2, *note log10: XREFlog10, *note logspace: XREFlogspace.

 -- : reallog (X)
     Return the real-valued natural logarithm of each element of X.

     If any element results in a complex return value ‘reallog’ aborts
     and issues an error.

     See also: *note log: XREFlog, *note realpow: XREFrealpow, *note
     realsqrt: XREFrealsqrt.

 -- : log1p (X)
     Compute ‘log (1 + X)’ accurately in the neighborhood of zero.

     See also: *note log: XREFlog, *note exp: XREFexp, *note expm1:
     XREFexpm1.

 -- : log10 (X)
     Compute the base-10 logarithm of each element of X.

     See also: *note log: XREFlog, *note log2: XREFlog2, *note logspace:
     XREFlogspace, *note exp: XREFexp.

 -- : log2 (X)
 -- : [F, E] = log2 (X)
     Compute the base-2 logarithm of each element of X.

     If called with two output arguments, split X into binary mantissa
     and exponent so that ‘1/2 <= abs(f) < 1’ and E is an integer.  If
     ‘x = 0’, ‘f = e = 0’.

     See also: *note pow2: XREFpow2, *note log: XREFlog, *note log10:
     XREFlog10, *note exp: XREFexp.

 -- : pow2 (X)
 -- : pow2 (F, E)
     With one input argument, compute 2 .^ x for each element of X.

     With two input arguments, return f .* (2 .^ e).

     See also: *note log2: XREFlog2, *note nextpow2: XREFnextpow2, *note
     power: XREFpower.

 -- : nextpow2 (X)
     Compute the exponent for the smallest power of two larger than the
     input.

     For each element in the input array X, return the first integer N
     such that 2^n ≥ abs (x).

     See also: *note pow2: XREFpow2, *note log2: XREFlog2.

 -- : realpow (X, Y)
     Compute the real-valued, element-by-element power operator.

     This is equivalent to ‘X .^ Y’, except that ‘realpow’ reports an
     error if any return value is complex.

     See also: *note power: XREFpower, *note reallog: XREFreallog, *note
     realsqrt: XREFrealsqrt.

 -- : sqrt (X)
     Compute the square root of each element of X.

     If X is negative, a complex result is returned.

     To compute the matrix square root, see *note Linear Algebra::.

     See also: *note realsqrt: XREFrealsqrt, *note nthroot: XREFnthroot.

 -- : realsqrt (X)
     Return the real-valued square root of each element of X.

     If any element results in a complex return value ‘realsqrt’ aborts
     and issues an error.

     See also: *note sqrt: XREFsqrt, *note realpow: XREFrealpow, *note
     reallog: XREFreallog.

 -- : cbrt (X)
     Compute the real cube root of each element of X.

     Unlike ‘X^(1/3)’, the result will be negative if X is negative.

     See also: *note nthroot: XREFnthroot.

 -- : nthroot (X, N)

     Compute the real (non-complex) N-th root of X.

     X must have all real entries and N must be a scalar.  If N is an
     even integer and X has negative entries then ‘nthroot’ aborts and
     issues an error.

     Example:

          nthroot (-1, 3)
          ⇒ -1
          (-1) ^ (1 / 3)
          ⇒ 0.50000 - 0.86603i

     See also: *note realsqrt: XREFrealsqrt, *note sqrt: XREFsqrt, *note
     cbrt: XREFcbrt.


File: octave.info,  Node: Complex Arithmetic,  Next: Trigonometry,  Prev: Exponents and Logarithms,  Up: Arithmetic

17.2 Complex Arithmetic
=======================

In the descriptions of the following functions, Z is the complex number
X + IY, where I is defined as ‘sqrt (-1)’.

 -- : abs (Z)
     Compute the magnitude of Z.

     The magnitude is defined as |Z| = ‘sqrt (x^2 + y^2)’.

     For example:

          abs (3 + 4i)
               ⇒ 5

     See also: *note arg: XREFarg.

 -- : arg (Z)
 -- : angle (Z)
     Compute the argument, i.e., angle of Z.

     This is defined as, THETA = ‘atan2 (Y, X)’, in radians.

     For example:

          arg (3 + 4i)
               ⇒ 0.92730

     See also: *note abs: XREFabs.

 -- : conj (Z)
     Return the complex conjugate of Z.

     The complex conjugate is defined as ‘conj (Z)’ = X - IY.

     See also: *note real: XREFreal, *note imag: XREFimag.

 -- : cplxpair (Z)
 -- : cplxpair (Z, TOL)
 -- : cplxpair (Z, TOL, DIM)
     Sort the numbers Z into complex conjugate pairs ordered by
     increasing real part.

     The negative imaginary complex numbers are placed first within each
     pair.  All real numbers (those with ‘abs (imag (Z)) / abs (Z) <
     TOL’) are placed after the complex pairs.

     TOL is a weighting factor in the range [0, 1) which determines the
     tolerance of the matching.  The default value is ‘100 * eps’ and
     the resulting tolerance for a given complex pair is ‘TOL * abs
     (Z(i)))’.

     By default the complex pairs are sorted along the first
     non-singleton dimension of Z.  If DIM is specified, then the
     complex pairs are sorted along this dimension.

     Signal an error if some complex numbers could not be paired.
     Signal an error if all complex numbers are not exact conjugates (to
     within TOL).  Note that there is no defined order for pairs with
     identical real parts but differing imaginary parts.

          cplxpair (exp (2i*pi*[0:4]'/5)) == exp (2i*pi*[3; 2; 4; 1; 0]/5)

 -- : imag (Z)
     Return the imaginary part of Z as a real number.

     See also: *note real: XREFreal, *note conj: XREFconj.

 -- : real (Z)
     Return the real part of Z.

     See also: *note imag: XREFimag, *note conj: XREFconj.


File: octave.info,  Node: Trigonometry,  Next: Sums and Products,  Prev: Complex Arithmetic,  Up: Arithmetic

17.3 Trigonometry
=================

Octave provides the following trigonometric functions where angles are
specified in radians.  To convert from degrees to radians multiply by
‘pi/180’ or use the ‘deg2rad’ function.  For example, ‘sin (30 *
pi/180)’ returns the sine of 30 degrees.  As an alternative, Octave
provides a number of trigonometric functions which work directly on an
argument specified in degrees.  These functions are named after the base
trigonometric function with a ‘d’ suffix.  As an example, ‘sin’ expects
an angle in radians while ‘sind’ expects an angle in degrees.

   Octave uses the C library trigonometric functions.  It is expected
that these functions are defined by the ISO/IEC 9899 Standard.  This
Standard is available at:
<http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf>.  Section
F.9.1 deals with the trigonometric functions.  The behavior of most of
the functions is relatively straightforward.  However, there are some
exceptions to the standard behavior.  Many of the exceptions involve the
behavior for -0.  The most complex case is atan2.  Octave exactly
implements the behavior given in the Standard.  Including ‘atan2(+- 0,
0)’ returns ‘+- pi’.

   It should be noted that MATLAB uses different definitions which
apparently do not distinguish -0.

 -- : RAD = deg2rad (DEG)

     Convert degrees to radians.

     The input DEG must be a scalar, vector, or N-dimensional array of
     double or single floating point values.  DEG may be complex in
     which case the real and imaginary components are converted
     separately.

     The output RAD is the same size and shape as DEG with degrees
     converted to radians using the conversion constant ‘pi/180’.

     Example:

          deg2rad ([0, 90, 180, 270, 360])
            ⇒  0.00000   1.57080   3.14159   4.71239   6.28319

     See also: *note rad2deg: XREFrad2deg.

 -- : DEG = rad2deg (RAD)

     Convert radians to degrees.

     The input RAD must be a scalar, vector, or N-dimensional array of
     double or single floating point values.  RAD may be complex in
     which case the real and imaginary components are converted
     separately.

     The output DEG is the same size and shape as RAD with radians
     converted to degrees using the conversion constant ‘180/pi’.

     Example:

          rad2deg ([0, pi/2, pi, 3/2*pi, 2*pi])
            ⇒  0    90   180   270   360

     See also: *note deg2rad: XREFdeg2rad.

 -- : sin (X)
     Compute the sine for each element of X in radians.

     See also: *note asin: XREFasin, *note sind: XREFsind, *note sinh:
     XREFsinh.

 -- : cos (X)
     Compute the cosine for each element of X in radians.

     See also: *note acos: XREFacos, *note cosd: XREFcosd, *note cosh:
     XREFcosh.

 -- : tan (Z)
     Compute the tangent for each element of X in radians.

     See also: *note atan: XREFatan, *note tand: XREFtand, *note tanh:
     XREFtanh.

 -- : sec (X)
     Compute the secant for each element of X in radians.

     See also: *note asec: XREFasec, *note secd: XREFsecd, *note sech:
     XREFsech.

 -- : csc (X)
     Compute the cosecant for each element of X in radians.

     See also: *note acsc: XREFacsc, *note cscd: XREFcscd, *note csch:
     XREFcsch.

 -- : cot (X)
     Compute the cotangent for each element of X in radians.

     See also: *note acot: XREFacot, *note cotd: XREFcotd, *note coth:
     XREFcoth.

 -- : asin (X)
     Compute the inverse sine in radians for each element of X.

     See also: *note sin: XREFsin, *note asind: XREFasind.

 -- : acos (X)
     Compute the inverse cosine in radians for each element of X.

     See also: *note cos: XREFcos, *note acosd: XREFacosd.

 -- : atan (X)
     Compute the inverse tangent in radians for each element of X.

     See also: *note tan: XREFtan, *note atand: XREFatand.

 -- : asec (X)
     Compute the inverse secant in radians for each element of X.

     See also: *note sec: XREFsec, *note asecd: XREFasecd.

 -- : acsc (X)
     Compute the inverse cosecant in radians for each element of X.

     See also: *note csc: XREFcsc, *note acscd: XREFacscd.

 -- : acot (X)
     Compute the inverse cotangent in radians for each element of X.

     See also: *note cot: XREFcot, *note acotd: XREFacotd.

 -- : sinh (X)
     Compute the hyperbolic sine for each element of X.

     See also: *note asinh: XREFasinh, *note cosh: XREFcosh, *note tanh:
     XREFtanh.

 -- : cosh (X)
     Compute the hyperbolic cosine for each element of X.

     See also: *note acosh: XREFacosh, *note sinh: XREFsinh, *note tanh:
     XREFtanh.

 -- : tanh (X)
     Compute hyperbolic tangent for each element of X.

     See also: *note atanh: XREFatanh, *note sinh: XREFsinh, *note cosh:
     XREFcosh.

 -- : sech (X)
     Compute the hyperbolic secant of each element of X.

     See also: *note asech: XREFasech.

 -- : csch (X)
     Compute the hyperbolic cosecant of each element of X.

     See also: *note acsch: XREFacsch.

 -- : coth (X)
     Compute the hyperbolic cotangent of each element of X.

     See also: *note acoth: XREFacoth.

 -- : asinh (X)
     Compute the inverse hyperbolic sine for each element of X.

     See also: *note sinh: XREFsinh.

 -- : acosh (X)
     Compute the inverse hyperbolic cosine for each element of X.

     See also: *note cosh: XREFcosh.

 -- : atanh (X)
     Compute the inverse hyperbolic tangent for each element of X.

     See also: *note tanh: XREFtanh.

 -- : asech (X)
     Compute the inverse hyperbolic secant of each element of X.

     See also: *note sech: XREFsech.

 -- : acsch (X)
     Compute the inverse hyperbolic cosecant of each element of X.

     See also: *note csch: XREFcsch.

 -- : acoth (X)
     Compute the inverse hyperbolic cotangent of each element of X.

     See also: *note coth: XREFcoth.

 -- : atan2 (Y, X)
     Compute atan (Y / X) for corresponding elements of Y and X.

     Y and X must match in size and orientation.  The signs of elements
     of Y and X are used to determine the quadrants of each resulting
     value.

     This function is equivalent to ‘arg (complex (X, Y))’.

     See also: *note tan: XREFtan, *note tand: XREFtand, *note tanh:
     XREFtanh, *note atanh: XREFatanh.

   Octave provides the following trigonometric functions where angles
are specified in degrees.  These functions produce true zeros at the
appropriate intervals rather than the small round-off error that occurs
when using radians.  For example:

     cosd (90)
          ⇒ 0
     cos (pi/2)
          ⇒ 6.1230e-17

 -- : sind (X)
     Compute the sine for each element of X in degrees.

     Returns zero for elements where ‘X/180’ is an integer.

     See also: *note asind: XREFasind, *note sin: XREFsin.

 -- : cosd (X)
     Compute the cosine for each element of X in degrees.

     Returns zero for elements where ‘(X-90)/180’ is an integer.

     See also: *note acosd: XREFacosd, *note cos: XREFcos.

 -- : tand (X)
     Compute the tangent for each element of X in degrees.

     Returns zero for elements where ‘X/180’ is an integer and ‘Inf’ for
     elements where ‘(X-90)/180’ is an integer.

     See also: *note atand: XREFatand, *note tan: XREFtan.

 -- : secd (X)
     Compute the secant for each element of X in degrees.

     See also: *note asecd: XREFasecd, *note sec: XREFsec.

 -- : cscd (X)
     Compute the cosecant for each element of X in degrees.

     See also: *note acscd: XREFacscd, *note csc: XREFcsc.

 -- : cotd (X)
     Compute the cotangent for each element of X in degrees.

     See also: *note acotd: XREFacotd, *note cot: XREFcot.

 -- : asind (X)
     Compute the inverse sine in degrees for each element of X.

     See also: *note sind: XREFsind, *note asin: XREFasin.

 -- : acosd (X)
     Compute the inverse cosine in degrees for each element of X.

     See also: *note cosd: XREFcosd, *note acos: XREFacos.

 -- : atand (X)
     Compute the inverse tangent in degrees for each element of X.

     See also: *note tand: XREFtand, *note atan: XREFatan.

 -- : atan2d (Y, X)
     Compute atan (Y / X) in degrees for corresponding elements from Y
     and X.

     See also: *note tand: XREFtand, *note atan2: XREFatan2.

 -- : asecd (X)
     Compute the inverse secant in degrees for each element of X.

     See also: *note secd: XREFsecd, *note asec: XREFasec.

 -- : acscd (X)
     Compute the inverse cosecant in degrees for each element of X.

     See also: *note cscd: XREFcscd, *note acsc: XREFacsc.

 -- : acotd (X)
     Compute the inverse cotangent in degrees for each element of X.

     See also: *note cotd: XREFcotd, *note acot: XREFacot.


File: octave.info,  Node: Sums and Products,  Next: Utility Functions,  Prev: Trigonometry,  Up: Arithmetic

17.4 Sums and Products
======================

 -- : sum (X)
 -- : sum (X, DIM)
 -- : sum (..., "native")
 -- : sum (..., "double")
 -- : sum (..., "extra")
     Sum of elements along dimension DIM.

     If DIM is omitted, it defaults to the first non-singleton
     dimension.

     The optional "type" input determines the class of the variable used
     for calculations.  By default, operations on floating point inputs
     (double or single) are performed in their native data type, while
     operations on integer, logical, and character data types are
     performed using doubles.  If the argument "native" is given, then
     the operation is performed in the same type as the original
     argument.

     For example:

          sum ([true, true])
             ⇒ 2
          sum ([true, true], "native")
             ⇒ true

     If "double" is given the sum is performed in double precision even
     for single precision inputs.

     For double precision inputs, the "extra" option will use a more
     accurate algorithm than straightforward summation.  For single
     precision inputs, "extra" is the same as "double".  For all other
     data type "extra" has no effect.

     See also: *note cumsum: XREFcumsum, *note sumsq: XREFsumsq, *note
     prod: XREFprod.

 -- : prod (X)
 -- : prod (X, DIM)
 -- : prod (..., "native")
 -- : prod (..., "double")
     Product of elements along dimension DIM.

     If DIM is omitted, it defaults to the first non-singleton
     dimension.

     The optional "type" input determines the class of the variable used
     for calculations.  If the argument "native" is given, then the
     operation is performed in the same type as the original argument,
     rather than the default double type.

     For example:

          prod ([true, true])
             ⇒ 1
          prod ([true, true], "native")
             ⇒ true

     On the contrary, if "double" is given, the operation is performed
     in double precision even for single precision inputs.

     See also: *note cumprod: XREFcumprod, *note sum: XREFsum.

 -- : cumsum (X)
 -- : cumsum (X, DIM)
 -- : cumsum (..., "native")
 -- : cumsum (..., "double")
     Cumulative sum of elements along dimension DIM.

     If DIM is omitted, it defaults to the first non-singleton
     dimension.  For example:

          cumsum ([1, 2; 3, 4; 5, 6])
             ⇒  1   2
                 4   6
                 9  12

     See ‘sum’ for an explanation of the optional parameters "native"
     and "double".

     See also: *note sum: XREFsum, *note cumprod: XREFcumprod.

 -- : cumprod (X)
 -- : cumprod (X, DIM)
     Cumulative product of elements along dimension DIM.

     If DIM is omitted, it defaults to the first non-singleton
     dimension.  For example:

          cumprod ([1, 2; 3, 4; 5, 6])
             ⇒  1   2
                 3   8
                15  48

     See also: *note prod: XREFprod, *note cumsum: XREFcumsum.

 -- : sumsq (X)
 -- : sumsq (X, DIM)
     Sum of squares of elements along dimension DIM.

     If DIM is omitted, it defaults to the first non-singleton
     dimension.

     This function is conceptually equivalent to computing

          sum (x .* conj (x), dim)

     but it uses less memory and avoids calling ‘conj’ if X is real.

     See also: *note sum: XREFsum, *note prod: XREFprod.


File: octave.info,  Node: Utility Functions,  Next: Special Functions,  Prev: Sums and Products,  Up: Arithmetic

17.5 Utility Functions
======================

 -- : ceil (X)
     Return the smallest integer not less than X.

     This is equivalent to rounding towards positive infinity.

     If X is complex, return ‘ceil (real (X)) + ceil (imag (X)) * I’.

          ceil ([-2.7, 2.7])
              ⇒ -2    3

     See also: *note floor: XREFfloor, *note round: XREFround, *note
     fix: XREFfix.

 -- : fix (X)
     Truncate fractional portion of X and return the integer portion.

     This is equivalent to rounding towards zero.  If X is complex,
     return ‘fix (real (X)) + fix (imag (X)) * I’.

          fix ([-2.7, 2.7])
             ⇒ -2    2

     See also: *note ceil: XREFceil, *note floor: XREFfloor, *note
     round: XREFround.

 -- : floor (X)
     Return the largest integer not greater than X.

     This is equivalent to rounding towards negative infinity.  If X is
     complex, return ‘floor (real (X)) + floor (imag (X)) * I’.

          floor ([-2.7, 2.7])
               ⇒ -3    2

     See also: *note ceil: XREFceil, *note round: XREFround, *note fix:
     XREFfix.

 -- : round (X)
     Return the integer nearest to X.

     If X is complex, return ‘round (real (X)) + round (imag (X)) * I’.
     If there are two nearest integers, return the one further away from
     zero.

          round ([-2.7, 2.7])
               ⇒ -3    3

     See also: *note ceil: XREFceil, *note floor: XREFfloor, *note fix:
     XREFfix, *note roundb: XREFroundb.

 -- : roundb (X)
     Return the integer nearest to X.  If there are two nearest
     integers, return the even one (banker’s rounding).

     If X is complex, return ‘roundb (real (X)) + roundb (imag (X)) *
     I’.

     See also: *note round: XREFround.

 -- : max (X)
 -- : max (X, [], DIM)
 -- : [W, IW] = max (X)
 -- : max (X, Y)
     Find maximum values in the array X.

     For a vector argument, return the maximum value.  For a matrix
     argument, return a row vector with the maximum value of each
     column.  For a multi-dimensional array, ‘max’ operates along the
     first non-singleton dimension.

     If the optional third argument DIM is present then operate along
     this dimension.  In this case the second argument is ignored and
     should be set to the empty matrix.

     For two matrices (or a matrix and a scalar), return the pairwise
     maximum.

     Thus,

          max (max (X))

     returns the largest element of the 2-D matrix X, and

          max (2:5, pi)
              ⇒  3.1416  3.1416  4.0000  5.0000

     compares each element of the range ‘2:5’ with ‘pi’, and returns a
     row vector of the maximum values.

     For complex arguments, the magnitude of the elements are used for
     comparison.  If the magnitudes are identical, then the results are
     ordered by phase angle in the range (-pi, pi].  Hence,

          max ([-1 i 1 -i])
              ⇒ -1

     because all entries have magnitude 1, but -1 has the largest phase
     angle with value pi.

     If called with one input and two output arguments, ‘max’ also
     returns the first index of the maximum value(s).  Thus,

          [x, ix] = max ([1, 3, 5, 2, 5])
              ⇒  x = 5
                  ix = 3

     See also: *note min: XREFmin, *note cummax: XREFcummax, *note
     cummin: XREFcummin.

 -- : min (X)
 -- : min (X, [], DIM)
 -- : [W, IW] = min (X)
 -- : min (X, Y)
     Find minimum values in the array X.

     For a vector argument, return the minimum value.  For a matrix
     argument, return a row vector with the minimum value of each
     column.  For a multi-dimensional array, ‘min’ operates along the
     first non-singleton dimension.

     If the optional third argument DIM is present then operate along
     this dimension.  In this case the second argument is ignored and
     should be set to the empty matrix.

     For two matrices (or a matrix and a scalar), return the pairwise
     minimum.

     Thus,

          min (min (X))

     returns the smallest element of the 2-D matrix X, and

          min (2:5, pi)
              ⇒  2.0000  3.0000  3.1416  3.1416

     compares each element of the range ‘2:5’ with ‘pi’, and returns a
     row vector of the minimum values.

     For complex arguments, the magnitude of the elements are used for
     comparison.  If the magnitudes are identical, then the results are
     ordered by phase angle in the range (-pi, pi].  Hence,

          min ([-1 i 1 -i])
              ⇒ -i

     because all entries have magnitude 1, but -i has the smallest phase
     angle with value -pi/2.

     If called with one input and two output arguments, ‘min’ also
     returns the first index of the minimum value(s).  Thus,

          [x, ix] = min ([1, 3, 0, 2, 0])
              ⇒  x = 0
                  ix = 3

     See also: *note max: XREFmax, *note cummin: XREFcummin, *note
     cummax: XREFcummax.

 -- : cummax (X)
 -- : cummax (X, DIM)
 -- : [W, IW] = cummax (...)
     Return the cumulative maximum values along dimension DIM.

     If DIM is unspecified it defaults to column-wise operation.  For
     example:

          cummax ([1 3 2 6 4 5])
             ⇒  1  3  3  6  6  6

     If called with two output arguments the index of the maximum value
     is also returned.

          [w, iw] = cummax ([1 3 2 6 4 5])
          ⇒
          w =  1  3  3  6  6  6
          iw = 1  2  2  4  4  4

     See also: *note cummin: XREFcummin, *note max: XREFmax, *note min:
     XREFmin.

 -- : cummin (X)
 -- : cummin (X, DIM)
 -- : [W, IW] = cummin (X)
     Return the cumulative minimum values along dimension DIM.

     If DIM is unspecified it defaults to column-wise operation.  For
     example:

          cummin ([5 4 6 2 3 1])
             ⇒  5  4  4  2  2  1

     If called with two output arguments the index of the minimum value
     is also returned.

          [w, iw] = cummin ([5 4 6 2 3 1])
          ⇒
          w =  5  4  4  2  2  1
          iw = 1  2  2  4  4  6

     See also: *note cummax: XREFcummax, *note min: XREFmin, *note max:
     XREFmax.

 -- : hypot (X, Y)
 -- : hypot (X, Y, Z, ...)
     Compute the element-by-element square root of the sum of the
     squares of X and Y.

     This is equivalent to ‘sqrt (X.^2 + Y.^2)’, but is calculated in a
     manner that avoids overflows for large values of X or Y.

     ‘hypot’ can also be called with more than 2 arguments; in this
     case, the arguments are accumulated from left to right:

          hypot (hypot (X, Y), Z)
          hypot (hypot (hypot (X, Y), Z), W), etc.

 -- : DX = gradient (M)
 -- : [DX, DY, DZ, ...] = gradient (M)
 -- : [...] = gradient (M, S)
 -- : [...] = gradient (M, X, Y, Z, ...)
 -- : [...] = gradient (F, X0)
 -- : [...] = gradient (F, X0, S)
 -- : [...] = gradient (F, X0, X, Y, ...)

     Calculate the gradient of sampled data or a function.

     If M is a vector, calculate the one-dimensional gradient of M.  If
     M is a matrix the gradient is calculated for each dimension.

     ‘[DX, DY] = gradient (M)’ calculates the one-dimensional gradient
     for X and Y direction if M is a matrix.  Additional return
     arguments can be use for multi-dimensional matrices.

     A constant spacing between two points can be provided by the S
     parameter.  If S is a scalar, it is assumed to be the spacing for
     all dimensions.  Otherwise, separate values of the spacing can be
     supplied by the X, ... arguments.  Scalar values specify an
     equidistant spacing.  Vector values for the X, ... arguments
     specify the coordinate for that dimension.  The length must match
     their respective dimension of M.

     At boundary points a linear extrapolation is applied.  Interior
     points are calculated with the first approximation of the numerical
     gradient

          y'(i) = 1/(x(i+1)-x(i-1)) * (y(i-1)-y(i+1)).

     If the first argument F is a function handle, the gradient of the
     function at the points in X0 is approximated using central
     difference.  For example, ‘gradient (@cos, 0)’ approximates the
     gradient of the cosine function in the point x0 = 0.  As with
     sampled data, the spacing values between the points from which the
     gradient is estimated can be set via the S or DX, DY, ...
     arguments.  By default a spacing of 1 is used.

     See also: *note diff: XREFdiff, *note del2: XREFdel2.

 -- : dot (X, Y, DIM)
     Compute the dot product of two vectors.

     If X and Y are matrices, calculate the dot products along the first
     non-singleton dimension.

     If the optional argument DIM is given, calculate the dot products
     along this dimension.

     This is equivalent to ‘sum (conj (X) .* Y, DIM)’, but avoids
     forming a temporary array and is faster.  When X and Y are column
     vectors, the result is equivalent to ‘X' * Y’.

     See also: *note cross: XREFcross, *note divergence: XREFdivergence.

 -- : cross (X, Y)
 -- : cross (X, Y, DIM)
     Compute the vector cross product of two 3-dimensional vectors X and
     Y.

     If X and Y are matrices, the cross product is applied along the
     first dimension with three elements.

     The optional argument DIM forces the cross product to be calculated
     along the specified dimension.

     Example Code:

          cross ([1,1,0], [0,1,1])
               ⇒ [ 1; -1; 1 ]

     See also: *note dot: XREFdot, *note curl: XREFcurl, *note
     divergence: XREFdivergence.

 -- : DIV = divergence (X, Y, Z, FX, FY, FZ)
 -- : DIV = divergence (FX, FY, FZ)
 -- : DIV = divergence (X, Y, FX, FY)
 -- : DIV = divergence (FX, FY)
     Calculate divergence of a vector field given by the arrays FX, FY,
     and FZ or FX, FY respectively.

                            d               d               d
          div F(x,y,z)  =   -- F(x,y,z)  +  -- F(x,y,z)  +  -- F(x,y,z)
                            dx              dy              dz

     The coordinates of the vector field can be given by the arguments
     X, Y, Z or X, Y respectively.

     See also: *note curl: XREFcurl, *note gradient: XREFgradient, *note
     del2: XREFdel2, *note dot: XREFdot.

 -- : [CX, CY, CZ, V] = curl (X, Y, Z, FX, FY, FZ)
 -- : [CZ, V] = curl (X, Y, FX, FY)
 -- : [...] = curl (FX, FY, FZ)
 -- : [...] = curl (FX, FY)
 -- : V = curl (...)
     Calculate curl of vector field given by the arrays FX, FY, and FZ
     or FX, FY respectively.

                            / d         d       d         d       d         d     \
          curl F(x,y,z)  =  | -- Fz  -  -- Fy,  -- Fx  -  -- Fz,  -- Fy  -  -- Fx |
                            \ dy        dz      dz        dx      dx        dy    /

     The coordinates of the vector field can be given by the arguments
     X, Y, Z or X, Y respectively.  V calculates the scalar component of
     the angular velocity vector in direction of the z-axis for
     two-dimensional input.  For three-dimensional input the scalar
     rotation is calculated at each grid point in direction of the
     vector field at that point.

     See also: *note divergence: XREFdivergence, *note gradient:
     XREFgradient, *note del2: XREFdel2, *note cross: XREFcross.

 -- : L = del2 (M)
 -- : L = del2 (M, H)
 -- : L = del2 (M, DX, DY, ...)

     Calculate the discrete Laplace operator.

     For a 2-dimensional matrix M this is defined as

                1    / d^2            d^2         \
          L  = --- * | ---  M(x,y) +  ---  M(x,y) |
                4    \ dx^2           dy^2        /

     For N-dimensional arrays the sum in parentheses is expanded to
     include second derivatives over the additional higher dimensions.

     The spacing between evaluation points may be defined by H, which is
     a scalar defining the equidistant spacing in all dimensions.
     Alternatively, the spacing in each dimension may be defined
     separately by DX, DY, etc.  A scalar spacing argument defines
     equidistant spacing, whereas a vector argument can be used to
     specify variable spacing.  The length of the spacing vectors must
     match the respective dimension of M.  The default spacing value is
     1.

     Dimensions with fewer than 3 data points are skipped.  Boundary
     points are calculated from the linear extrapolation of interior
     points.

     Example: Second derivative of 2*x^3

          f = @(x) 2*x.^3;
          dd = @(x) 12*x;
          x = 1:6;
          L = 4*del2 (f(x));
          assert (L, dd (x));

     See also: *note gradient: XREFgradient, *note diff: XREFdiff.

 -- : factorial (N)
     Return the factorial of N where N is a real non-negative integer.

     If N is a scalar, this is equivalent to ‘prod (1:N)’.  For vector
     or matrix arguments, return the factorial of each element in the
     array.

     For non-integers see the generalized factorial function ‘gamma’.
     Note that the factorial function grows large quite quickly, and
     even with double precision values overflow will occur if N > 171.
     For such cases consider ‘gammaln’.

     See also: *note prod: XREFprod, *note gamma: XREFgamma, *note
     gammaln: XREFgammaln.

 -- : PF = factor (Q)
 -- : [PF, N] = factor (Q)
     Return the prime factorization of Q.

     The prime factorization is defined as ‘prod (PF) == Q’ where every
     element of PF is a prime number.  If ‘Q == 1’, return 1.

     With two output arguments, return the unique prime factors PF and
     their multiplicities.  That is, ‘prod (PF .^ N) == Q’.

     Implementation Note: The input Q must be less than ‘flintmax’
     (9.0072e+15) in order to factor correctly.

     See also: *note gcd: XREFgcd, *note lcm: XREFlcm, *note isprime:
     XREFisprime, *note primes: XREFprimes.

 -- : G = gcd (A1, A2, ...)
 -- : [G, V1, ...] = gcd (A1, A2, ...)
     Compute the greatest common divisor of A1, A2, ....

     If more than one argument is given then all arguments must be the
     same size or scalar.  In this case the greatest common divisor is
     calculated for each element individually.  All elements must be
     ordinary or Gaussian (complex) integers.  Note that for Gaussian
     integers, the gcd is only unique up to a phase factor
     (multiplication by 1, -1, i, or -i), so an arbitrary greatest
     common divisor among the four possible is returned.

     Optional return arguments V1, ..., contain integer vectors such
     that,

          G = V1 .* A1 + V2 .* A2 + ...

     Example code:

          gcd ([15, 9], [20, 18])
             ⇒  5  9

     See also: *note lcm: XREFlcm, *note factor: XREFfactor, *note
     isprime: XREFisprime.

 -- : lcm (X, Y)
 -- : lcm (X, Y, ...)
     Compute the least common multiple of X and Y, or of the list of all
     arguments.

     All elements must be numeric and of the same size or scalar.

     See also: *note factor: XREFfactor, *note gcd: XREFgcd, *note
     isprime: XREFisprime.

 -- : rem (X, Y)
     Return the remainder of the division ‘X / Y’.

     The remainder is computed using the expression

          x - y .* fix (x ./ y)

     An error message is printed if the dimensions of the arguments do
     not agree, or if either argument is complex.

     Programming Notes: Floating point numbers within a few eps of an
     integer will be rounded to an integer before computation for
     compatibility with MATLAB.

     By convention,

          rem (X, 0) = NaN  if X is a floating point variable
          rem (X, 0) = 0    if X is an integer variable
          rem (X, Y)        returns a value with the signbit from X

     For the opposite conventions see the ‘mod’ function.  In general,
     ‘rem’ is best when computing the remainder after division of two
     _positive_ numbers.  For negative numbers, or when the values are
     periodic, ‘mod’ is a better choice.

     See also: *note mod: XREFmod.

 -- : mod (X, Y)
     Compute the modulo of X and Y.

     Conceptually this is given by

          x - y .* floor (x ./ y)

     and is written such that the correct modulus is returned for
     integer types.  This function handles negative values correctly.
     That is, ‘mod (-1, 3)’ is 2, not -1, as ‘rem (-1, 3)’ returns.

     An error results if the dimensions of the arguments do not agree,
     or if either of the arguments is complex.

     Programming Notes: Floating point numbers within a few eps of an
     integer will be rounded to an integer before computation for
     compatibility with MATLAB.

     By convention,

          mod (X, 0) = X
          mod (X, Y)      returns a value with the signbit from Y

     For the opposite conventions see the ‘rem’ function.  In general,
     ‘mod’ is a better choice than ‘rem’ when any of the inputs are
     negative numbers or when the values are periodic.

     See also: *note rem: XREFrem.

 -- : P = primes (N)
     Return all primes up to N.

     The output data class (double, single, uint32, etc.) is the same as
     the input class of N.  The algorithm used is the Sieve of
     Eratosthenes.

     Note: If you need a specific number of primes you can use the fact
     that the distance from one prime to the next is, on average,
     proportional to the logarithm of the prime.  Integrating, one finds
     that there are about k primes less than k*log (5*k).

     See also ‘list_primes’ if you need a specific number N of primes.

     See also: *note list_primes: XREFlist_primes, *note isprime:
     XREFisprime.

 -- : list_primes ()
 -- : list_primes (N)
     List the first N primes.

     If N is unspecified, the first 25 primes are listed.

     See also: *note primes: XREFprimes, *note isprime: XREFisprime.

 -- : sign (X)
     Compute the “signum” function.

     This is defined as

                     -1, x < 0;
          sign (x) =  0, x = 0;
                      1, x > 0.

     For complex arguments, ‘sign’ returns ‘x ./ abs (X)’.

     Note that ‘sign (-0.0)’ is 0.  Although IEEE 754 floating point
     allows zero to be signed, 0.0 and -0.0 compare equal.  If you must
     test whether zero is signed, use the ‘signbit’ function.

     See also: *note signbit: XREFsignbit.

 -- : signbit (X)
     Return logical true if the value of X has its sign bit set and
     false otherwise.

     This behavior is consistent with the other logical functions.  See
     *note Logical Values::.  The behavior differs from the C language
     function which returns nonzero if the sign bit is set.

     This is not the same as ‘x < 0.0’, because IEEE 754 floating point
     allows zero to be signed.  The comparison ‘-0.0 < 0.0’ is false,
     but ‘signbit (-0.0)’ will return a nonzero value.

     See also: *note sign: XREFsign.

