Continuando da qui sono qui; anzi no è solo un elenco, passo qui.

Introduzione alle strutture grafiche

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`

, and `image`

.

Each of these objects has a function by the same name, and, each of these functions returns a graphics handle pointing to an object of 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 Data Sources.

The graphics objects are arranged in a hierarchy:

- The root is at 0. In other words,
`get (0)`

returns the properties of the root object.
- Below the root are
`figure`

objects.
- Below the
`figure`

objects are `axes`

objects.
- Below the
`axes`

objects are `line`

, `text`

, `patch`

, `surface`

, and `image`

objects.

Graphics handles may be distinguished from function handles by means of the function `ishandle`

. `ishandle`

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. The test functions return true only if the argument is both a handle and of the correct type (`figure`

or `axes`

).

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:

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

.

Se ne riparlerà ancora; anche perché finora… (impressione perso: a volte Octave vuole fare troppo).

Function File: `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.

Avanti, qui.

**Oggetti grafici**

The hierarchy of graphics objects was explained above. Here the specific objects are described, and the properties contained in these objects are discussed. Keep in mind that graphics objects are always referenced by handle.

`root figure`

The top level of the hierarchy and the parent of all `figure`

objects. The handle index of the `root figure`

is 0.
`figure`

A figure window.
`axes`

A set of axes. This object is a child of a `figure`

object and may be a parent of `line`

, `text`

, `image`

, `patch`

, or `surface`

objects.
`line`

A line in two or three dimensions.
`text`

Text annotations.
`image`

A bitmap image.
`patch`

A filled polygon, currently limited to two dimensions.
`surface`

A three-dimensional surface.

**Creare oggetti grafici**

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`

, and `surface`

functions. These fundamental graphic objects automatically become children of the current `axes`

object as if hold on was in place. Seperately, `axes`

will automatically become children of the current `figure`

object and figures will become children of the `root`

object 0.

If this auto-joining feature is not desired then it is important to call `newplot`

first to prepare a new figure and axes for plotting. Alternatively, the easier way is to call a high-level graphics routine which will both create the `plot`

and then populate it with low-level graphics objects. Instead of calling `line`

, use `plot`

. Or use `surf`

instead of `surface`

. Or use `fill`

instead of `patch`

.

Function File: `axes ()`

Function File: `axes (property, value, ...)`

Function File: `axes (hax)`

Function File: `h = axes (...)`

Create an `axes`

object and return a handle to it, or set the current `axes`

to `hax`

.

Called without any arguments, or with property/value pairs, construct a new axes. For accepted properties and corresponding values, see `set`

.

Called with a single axes handle argument `hax`

, the function makes hax the current axis. It also restacks the axes in the corresponding figure so that `hax`

is the first entry in the list of children. This causes `hax`

to be displayed on top of any other axes objects (Z-order stacking).

Function File: `line ()`

Function File: `line (x, y)`

Function File: `line (x, y, property, value, ...)`

Function File: `line (x, y, z)`

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

Function File: `line (property, value, ...)`

Function File: `line (hax, ...)`

Function File: `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 axis, 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.

Function File: `patch ()`

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

Function File: `patch (x, y, z, c)`

Function File: `patch (fv)`

Function File: `patch ("Faces", faces, "Vertices", verts, ...)`

Function File: `patch (..., prop, val, ...)`

Function File: `patch (hax, ...)`

Function File: `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.

A third input form is to create a structure `fv`

with the fields `"vertices"`

, `"faces"`

, and optionally `"facevertexcdata"`

.

If the first argument `hax`

is an axes handle, then plot into this axis, rather than the current axes returned by gca.

The optional return value `h`

is a graphics handle to the created patch object.

Implementation **Note**: Patches are highly configurable objects. To truly customize them requires setting `patch`

properties directly. Useful `patch`

properties are: `"cdata"`

, `"edgecolor"`

, `"facecolor"`

, `"faces"`

, `"facevertexcdata"`

.

`x = [0 1 1 0];`

`y = [0 0 1 1];`

`patch(x,y,'red')`

`x2 = [2 5; 2 5; 8 8];`

`y2 = [4 0; 8 2; 4 0];`

`patch(x2,y2,'green')`

`x = [2 5; 2 5; 8 8];`

`y = [4 0; 8 2; 4 0];`

`c = [0; 1];`

`patch(x,y,c)`

`colorbar`

Gli esempi li ho presi da qui dove ce ne sono altri più complessi.

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

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

Function File: `surface (z, c)`

Function File: `surface (z)`

Function File: `surface (..., prop, val, ...)`

Function File: `surface (hax, ...)`

Function File: `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:rows (z)`

and `y`

is `1:columns (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 axis, rather than the current axes returned by gca.

The optional return value `h`

is a graphics handle to the created surface object.

**Funzioni per gli handles**

To determine whether a variable is a graphics object index, or an index to an `axes`

or `figure`

, use the functions `ishandle`

, `isaxes`

, and `isfigure`

.

Built-in Function: `ishandle (h)`

Return true if `h`

is a graphics handle and false otherwise.

`h`

may also be a matrix of handles in which case a logical array is returned that is true where the elements of `h`

are graphics handles and false where they are not.

Function File: `ishghandle (h)`

Return true if `h`

is a graphics handle and false otherwise.

This function is equivalent to `ishandle`

and is provided for compatibility with MATLAB.

Function File: `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.

Function File: `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.

The function `gcf`

returns an index to the current figure object, or creates one if none exists. Similarly, `gca`

returns the current axes object, or creates one (and its parent figure object) if none exists.

Function File: `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.

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

`fig = gcf ();`

`set (fig, "numbertitle", "off", "name", "sin plot")`

visto il titolo della finestra?

**Note**: To find the current `figure`

without creating a new one if it does not exist, query the `"CurrentFigure"`

property of the root graphics object: `get (0, "currentfigure")`

.

Function File: `h = gca ()`

Return a handle to the current axis object.

The current axis 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.

`# con la finestra precedente`

`ax = gca ();`

`set (ax, "position", [0.5, 0.5, 0.5, 0.5]);`

**Note**: To find the current axis without creating a new axes object if it does not exist, query the `"CurrentAxes"`

property of a figure: `get (gcf, "currentaxes")`

.

Function File: `h = gco ()`

Function File: `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.

The `get`

and `set`

functions may be used to examine and set properties for graphics objects. For example `get (0)`

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,

To `set`

graphics object properties, use the `set`

function. For example, (sempre sulla finestra precedente) `set (gca (), "xlim", [-5, 6]);`

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.

Built-in Function: `val = get (h)`

Built-in Function: `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.

Built-in Function: `set (h, property, value, ...)`

Built-in Function: `set (h, properties, values)`

Built-in Function: `set (h, pv)`

Built-in Function: `value_list = set (h, property)`

Built-in Function: `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.

Function File: `parent = ancestor (h, type)`

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

Return the first `ancestor`

of handle object h whose type matches `type`

, where `type`

is a character string.

If `type`

is a cell array of strings, return the first parent whose `type`

matches any of the given type strings.

If the handle object `h`

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.

Function File: `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.

Function File: `findfigs ()`

Find all visible figures that are currently off the screen and move them onto the screen.

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

Function File: `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"`

.

Function File: `h = struct2hdl (s)`

Function File: `h = struct2hdl (s, p)`

Function File: `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.

Function File: `hnew = copyobj (horig)`

Function File: `hnew = copyobj (horig, hparent)`

Construct a copy of the graphic object associated with handle `horig`

and return a handle `hnew`

to the new object.

If a parent handle `hparent`

(root, figure, axes, or hggroup) is specified, the copied object will be created as a child of hparent.

Chissà se…😳