Region associated with an ID.
activeregion(xmin, xmax, ymin, ymax, id) activeregion(X, Y, id)
The command activeregion defines invisible regions with an ID for interactive manipulations in Sysquake. Contrary to most other graphical objects, a hit is detected when the mouse is inside the region, not close like with points and lines.
activeregion(xmin,xmax,ymin,ymax,id) defines a rectangular shape.
activeregion(X,Y,id) defines a polygonal shape. The start and end points do not have to be the same; the shape is closed automatically.
Rectangular button. If an ID was given to plot without activeregion, a hit would be detected when the mouse is close to any of the four corners; with activeregion, a hit is detected when the mouse is inside the rectangle.
plot([50, 70, 70, 50, 50], [10, 10, 30, 30, 10]); activeregion(50, 70, 10, 30, 1);
Area plot.
area(y) area(x, y) area(x, y, y0) area(..., style) area(..., style, id)
With column vector arguments, area(x,y) displays the area between the horizontal axis y=0 and the points given by x and y. When the second argument is an array with as many rows as elements in x, area(x,Y) displays the contribution of each column of Y, summed along each row. When both the first and second arguments are arrays of the same size, area(X,Y) displays independent area plots for corresponding columns of X and Y without summation.
With a single argument, area(y) takes integers 1, 2, ..., n for the horizontal coordinates.
With a third argument, area(x,y,y0) displays the area between the horizontal line y=y0 and values defined by y.
The optional arguments style and id have their usual meaning. area uses default colors when argument style is missing.
area(rand(20,10))
Vertical bar plot.
bar(y) bar(x, y) bar(x, y, w) bar(..., kind) bar(..., kind, style) bar(......, id)
bar(x,y) plots the columns of y as vertical bars centered around the corresponding value in x. If x is not specified, its default value is 1:size(y,2).
bar(x,y,w), where w is scalar, specifies the relative width of each bar with respect to the horizontal distance between the bars; with values smaller than 1, bars are separated with a gap, while with values larger than 1, bars overlap. If w is a vector of two components [w1,w2], w1 corresponds to the relative width of each bar in a group (columns of y), and w2 to the relative width of each group. Default values, used if w is missing or is the empty matrix [], is 0.8 for both w1 and w2.
bar(...,kind), where kind is a string, specifies the kind of bar plot. The following values are recognized:
| 'grouped' | Columns of y are grouped horizontally (default) |
| 'stacked' | Columns of y are stacked vertically |
| 'interval' | Bars defined with min and max val. |
With 'interval', intervals are defined by two consecutive rows of y, which must have an even number of rows.
The optional arguments style and id have their usual meaning. bar uses default colors when argument style is missing.
Simple bar plot
bar([2,4,3,6;3,5,4,1]);
Stacked bar plot:
bar(1:4, magic(4), [], 'stacked');
Interval plot:
bar(1:4, [2,4,3,1;5,6,4,6], [], 'interval');
Horizontal bar plot.
barh(x) barh(y, x) barh(y, x, w) barh(..., kind) barh(..., kind, style) barh(..., id)
barh plots a bar plot with horizontal bars. Please see bar for a description of its behavior and arguments.
Simple horizontal bar plot:
barh([2,4,3,6;3,5,4,1]);
Stacked horizontal bar plot:
barh(1:4, magic(4), [], 'stacked');
Horizontal interval plot:
barh(1:4, [2,4,3,1;5,6,4,6], [], 'interval');
Add circles to the figure.
circle(x,y,r) circle(x,y,r,style) circle(x,y,r,style,id)
circle(x,y,r) draws a circle of radius r centered at (x,y). The arguments can be vectors to display several circles. Their dimensions must match; scalar numbers are repeated if necessary. The optional fourth and fifth arguments are the style and object ID (cf. their description above).
In mouse handlers, _x0 and _y0 correspond to the projection of the mouse click onto the circle; _nb is the index of the circle in x, y and r, and _ix is empty.
Circles are displayed as circles only if the scales along the x and y axis are the same, and linear. With different linear scales, circles are displayed as ellipses. With logarithmic scales, they are not displayed.
circle(1, 2, 5, 'r', 1); circle(zeros(10,1), zeros(10, 1), 1:10);
Current colormap from scalar to RGB.
colormap(clut) clut = colormap
Command colormap(clut) changes the color mapping from scalar values to RGB values used by commands such as pcolor, image and surf.
Colormaps are arrays of size n-by-3. Each row corresponds to a color; the first column is the intensity of red from 0 (no red component) to 1 (maximum intensity), the second column the intensity of green, and the third column the intensity of blue. Input values are mapped uniformly to one of the discrete color entries, 0 to the first row and 1 to the last row.
With an input argument, colormap(clut) sets the colormap to clut. With an output argument, colormap returns the current colormap.
Level curves.
contour(z) contour(z, [xmin, xmax, ymin, ymax]) contour(z, [xmin, xmax, ymin, ymax], levels) contour(z, [xmin, xmax, ymin, ymax], levels, style)
contour(z) plots seven contour lines corresponding to the surface whose samples at equidistant points 1:size(z,2) in the x direction and 1:size(z,1) on the y direction are given by z. Contour lines are at equidistant levels. With a second non-empty argument [xmin, xmax, ymin, ymax], the samples are at equidistant points between xmin and xmax in the x direction and between ymin and ymax in the y direction.
The optional third argument levels, if non-empty, gives the number of contour lines if it is a scalar or the levels themselves if it is a vector.
The optional fourth argument is the style of each line, from the minimum to the maximum level (styles are recycled if necessary). The default style is 'kbrmgcy'.
When the style is f for a filled region, the corresponding level is filled on the side with a lower value of z. If the style argument is the single character 'f', all levels are filled with the default colors. Regions with a value of z smaller than the lowest level are left transparent; an explicit lower level should be specified to fill the whole rectangle.
A function is evaluated over a grid of two variables x and
y, and is drawn with contour
(x, y) = meshgrid(-2 + (0:40) / 10);
z = exp(-((x-0.2).^2+(y+0.3).^2)) ...
- exp(-((x+0.5).^2+(y-0.1).^2)) + 0.1 * x;
scale equal;
contour(z, [-1,1,-1,1]);
Filled contours:
u = -2 + (0:80) / 20;
x = repmat(u, 81, 1);
y = x';
z = exp(-((x-0.2).^2+(y+0.3).^2)) ...
- exp(-((x+0.5).^2+(y-0.1).^2)) ...
+ 0.1 * x ...
+ 0.5 * sin(y);
levels = -1:0.2:1;
scale equal;
contour(z, [-1,1,-1,1], levels, 'f');
Options for fonts.
options = fontset options = fontset(name1, value1, ...) options = fontset(options0, name1, value1, ...)
fontset(name1,value1,...) creates the font description used by text. Options are specified with name/value pairs, where the name is a string which must match exactly the names in the table below. Case is significant. Options which are not specified have a default value. The result is a structure whose fields correspond to each option. Without any input argument, fontset creates a structure with all the default options.
When its first input argument is a structure, fontset adds or changes fields which correspond to the name/value pairs which follow.
Here is the list of permissible options (empty arrays mean "automatic"):
| Name | Default | Meaning |
|---|---|---|
| Font | '' | font name |
| Size | 10 | character size in points |
| Bold | false | true for bold font |
| Italic | false | true for italic font |
| Underline | false | true for underline characters |
| Color | [0,0,0] | text color |
The default font is used if the font name is not recognized. The color is specified as an empty array (black), a scalar (gray) or a 3-element vector (RGB) of class double (0=black, 1=maximum brightness) or uint8 (0=black, 255=maximum brightness).
Default font:
fontset Font: '' Size: 10 Bold: false Italic: false Underline: false Color: real 1x3
Function plot.
fplot(fun) fplot(fun, limits) fplot(fun, limits, style) fplot(fun, limits, style, id) fplot(fun, limits, style, id, p1, p2, ...)
Command fplot(fun,limits) plots function fun, specified by its name as a string, a function reference, or an inline function. The function is plotted for x between limit(1) and limit(2); the default limits are [-5,5].
The optional third and fourth arguments are the same as for all graphical commands.
Remaining input arguments of fplot, if any, are given as additional input arguments to function fun. They permit to parameterize the function. For example fplot('fun',[0,10],'',-1,2,5) calls fun as y=fun(x,2,5) and displays its value for x between 0 and 10.
Plot a sine:
fplot(@sin);
Plot
fun = inline(... 'function y=f(x,a); y=(x+0.3)^2+a*exp(-3*x^2);'); fplot(fun, [-2,3], 'r', 1, 7.2);
Raster RGB or grayscale image.
image(gray) image(red, green, blue) image(rgb) image(..., [xmin, xmax, ymin, ymax]) image(..., style) image(..., id)
image displays a raster image (an image defined by a rectangular array of patches of colors called pixels). The raster image can be either grayscale or color. A grayscale image is defined by a double matrix of pixel values in the range 0 (black) to 1 (white), or by a uint8 matrix in the range 0 (black) to 255 (white). A color image is defined by three matrices of equal size, corresponding to the red, green, and blue components, or by an array with three planes along the 3rd dimension. Each component is defined between 0 (black) to 1 (maximum intensity) with double values, or between 0 (black) to 255 (maximum intensity) with uint8 values.
The position is defined by the the minimum and maximum coordinates along the horizontal and vertical axis. The raster image is scaled to fit. The first line of the matrix or matrices is displayed at the top. If style is 'e', the raster image is scaled down such that each pixel has the same size; otherwise, the specified position is filled with the raster image. You should use 'e' when you want a better quality, but do not add other elements in the figure (such as marks or lines) and do not have interaction with the mouse.
Pixels on the screen are interpolated using the bilinear method if style is '1', and the bicubic method if style is '3'.
Two ways to display a table of 10-by-10 random color cells
image(rand(10), rand(10), rand(10)); image(rand(10, 10, 3));
A ramp of gray shades:
image(uint8(0:255));
Operator : and function meshgrid can be used to create the x and y coordinates used to display a function z(x,y) as an image.
(X, Y) = meshgrid(-pi:0.1:pi); Z = cos(X.^2 + Y.^2).^2; image(Z, [-1,1,-1,1], '3');
Plot labels.
label(label_x) label(label_x, label_y)
label(label_x, label_y) displays labels for the X and Y axis. Its arguments are strings. The label for the Y axis may be omitted.
step(1,[1,2,3,4]);
label('t [s]', 'y [m]');
With literal strings, the command syntax may be more convenient:
label Re Im;
Plot legend.
legend(str) legend(str, style)
legend(str,style) displays legends for styles defined in string style. In string str, legends are separated by linefeed characters \n. Legends are displayed at the top right corner of the figure in a frame. All styles are permitted: symbols, lines, and filling. They are recycled if more legends are defined in str.
With a single input argument, legend(str) uses the default style 'k'.
Legend for two traces
plot(1:20, [rand(1,20); randn(1,20)], '_x');
legend('Uniform random\nNormal random', '_x');
Plot lines.
line(A, b) line(A, b, style) line(A, b, style, id)
line displays one or several straight line(s). Each line is
defined by an equation of the form
In figures with a logarithmic scale, only horizontal and vertical lines are allowed.
The optional third and fourth arguments are the same as for all graphical commands.
In mouse handlers, _x0 and _y0 correspond to the projection of the mouse position onto the line; _nb is the index of the line in A and b, and _ix is empty.
Vertical line at x=5:
line([1,0],5)
Draggable horizontal lines at y=2 and y=3:
line([0,1],[2;3],'b',1)
Pseudocolor plot.
pcolor(C) pcolor(X, Y, C) pcolor(..., style) pcolor(..., style, id)
Command pcolor(C) displays a pseudocolor plot, i.e. a rectangular array where the color of each cell corresponds to the value of elements of 2-D array C. These values are real numbers between 0 and 1. The color used by pcolor depends on the current color map; the default is a grayscale from black (0) to white (1).
pcolor(X,Y,C) displays the plot on a grid whose vertex coordinates are given by arrays X and Y. Arrays X, X and C must all have the same size.
With an additional string input argument, pcolor(...,style) specifies the style of the lines drawn between the cells.
The following argument, if it exists, is the ID used for interactivity. During interactive manipulation, the index obtained with _ix corresponds to the corner of the patch under the mouse with the smallest index.
use colormaps; n = 11; (x, y) = meshgrid(1:n); phi = pi/8; X = x*cos(phi)-y*sin(phi); Y = x*sin(phi)+y*cos(phi); C = magic(n)/n^2; pcolor(X, Y, C, 'k'); colormap(blue2yellow2redcm); plotoption noframe;
Generic plot.
plot(y) plot(x, y) plot(..., style) plot(..., style, id)
The command plot displays graphical data in the current figure. The data are given as two vectors of coordinates x and y. If x is omitted, its default value is 1:size(y,2). Depending on the style, the points are displayed as individual marks or are linked with lines. The stairs style ('s') can be used to link two successive points with a horizontal line followed by a vertical line. If x and y are matrices, each row is considered as a separate line or set of marks; if only one of them is a matrix, the other one, a row or column vector, is replicated to match the size of the other argument.
The optional fourth argument is an identification number which is used for interactive manipulation. It should be equal or larger than 1. If present and a mousedown, mousedrag and/or mouseup handler exists, the position of the mouse where the click occurs is mapped to the closest graphical element which has been displayed with an ID; for the command plot, the closest point is considered (lines linking the points are ignored). If such a point is found at a small distance, the built-in variables _x0, _y0, and _z0 are set to the position of the point before it is moved; the variable _id is set to the ID as defined by the command plot; the variable _nb is set to the number of the row, and the variable _ix is set to the index of the column of the matrix x and y.
Sine between 0 and
x = 2 * pi * (0:100) * 0.01; y = sin(x); plot(x, y);
Ten random crosses:
plot(rand(1,10), rand(1,10), 'x');
A complete SQ file for displaying a red triangle whose corners can be moved interactively on Sysquake:
variables x, y // x and y are 1-by-3 vectors
init (x,y) = init // init handler
figure "Triangle"
draw drawTri(x, y)
mousedrag (x, y) = dragTri(x, y, _ix, _x1, _y1)
functions
{@
function (x,y) = init
x = [-1,1,0];
y = [-1,-1,2];
subplots('Triangle');
function drawTri(x,y)
scale('equal', [-3, 3; -3, 3]);
plot(x, y, 'rf', 1); % filled red triangle with ID 1
function (x, y) = dragTri(x, y, ix, x1, y1)
if isempty(ix)
cancel; % not a click over a point
end
x(ix) = x1;
y(ix) = y1;
@}
Set plot options.
plotoption(str)
plotoption sets the initial value of one of the plot options the user can change. Its single argument, a character string, can take one of the following values.
Display of a photographic image without frame:
plotoption noframe; image(photo);
Polar plot.
polar(theta, rho) polar(..., style) polar(..., style, id)
Command polar displays graphical data in the current figure with polar coordinates. The data are given as two vectors of coordinates theta (in radians) and rho. Depending on the style, the points are displayed as individual marks or are linked with lines. If x and y are matrices, each row is considered as a separate line or set of marks; if only one of them is a matrix, the other one, a vector, is reused for each line.
Automatic scaling is performed the same way as for cartesian plots after polar coordinates have been converted. The figure axis, ticks and grids are specific to polar plots. Polar plots can be mixed with other graphical commands based on cartesian coordinates such as plot, line and circle.
theta = 0:0.01:20*pi; rho = exp(0.1 * theta) .* sin(5 * theta); polar(theta, rho);
Quiver plot.
quiver(x, y, u, v) quiver(u, v) quiver(..., scale) quiver(..., style)
quiver(x,y,u,v) displays vectors (u,v) starting at (x,y). If the four arguments are matrices of the same size, an arrow is drawn for each corresponding element. If x and y are vectors, they are repeated: x is transposed to a row vector if necessary and repeated to match the number of rows of u and v; and y is transposed to a column vector if necessary and repeated to match their number of columns. The absolute size of arrows is scaled with the average step of the grid given by x and y, so that they do not overlap if the grid is uniform.
If x and y are missing, their default values are [1,2,...,m] and [1,2,...,n] respectively, where m and n are the number of rows and columns of u and v.
With a 5th (or 3rd) argument, quiver(...,scale) multiplies the arrow lengths by the scalar number scale. If scale is zero, arrows are not scaled at all: u and v give directly the absolute value of the vectors.
With a 6th (or 4th) string argument, quiver(...,style) uses the specified style to draw the arrows.
Force field; complex numbers are used to simplify computation.
scale equal; z = fevalx(@plus, -5:0.5:5, 1j*(-5:0.5:5)'); z0 = 0.2+0.3j; f = 1+20*sign(z-z0)./(max(abs(z-z0).^2,3)); x = real(z); y = imag(z); u = real(f); v = imag(f); quiver(x, y, u, v);
Set the scale.
scale([xmin,xmax,ymin,ymax]) scale([xmin,xmax]) scale([xmin,xmax,ymin,ymax,zmin,zmax]) scale(features) scale(features, usersettablefeatures) scale(features, [xmin,xmax,ymin,ymax]) scale(features, usersettablefeatures, [xmin,xmax,ymin,ymax]) sc = scale
Without output argument, the scale command, which should be placed before any other graphical command, sets the scale and scale options. The last parameter contains the limits of the plot, either for both x and y axis or only for the x axis in 2D graphics, or for x, y and z axis for 3D graphics. The limits are used only if the user has not changed them by zooming.
The first parameter(s) specify some properties of the scale, and which one can be changed by the user. There are two ways to specify them: with a string or with one or two integer numbers. The recommended way is with a string. The list below enumerates the possible values.
This last setting shows how to enable the options the user can choose in Sysquake. The setting and the enabled options are separated by a dash; if a simple setting is specified, the enabled options are assumed to be the same. Enabling dB always permits the user to choose a logarithmic or linear scale, and enabling a logarithmic scale always permits to choose a linear scale. The 'equal' option cannot be combined with anything else.
When the properties are specified with one or two integer numbers, each bit corresponds to a property. Only the properties in bold in the table below can be set by the user, whatever the setting is.
| Bit | Meaning |
|---|---|
| 0 | log x |
| 2 | tick on x axis |
| 3 | grid for x axis |
| 4 | labels on x axis |
| 6 | log y |
| 7 | dB y |
| 8 | tick on y axis |
| 9 | grid for y axis |
| 10 | labels on y axis |
| 12 | same scale on both axis |
| 13 | minimum grid |
| 14 | maximum grid |
scale lock locks the scale as if the user had done it by hand. It fixes only the initial value; the user may change it back afterwards.
The scale is usually limited to a range of 1e-6 for linear scales and a ratio of 1e-6 for logarithmic scales. This avoids numerical problems, such as when a logarithmic scale is chosen and the data contain the value 0. In some rare cases, a large scale may be required. The 'lock' option is used to push the limits from 1e-6 to 1e-24 for both linear and logarithmic scales. A second argument must be provided:
scale('lock', [xmin,xmax,ymin,ymax]);
The command must be used in a draw handler (or from the command line interface). To add other options, use a separate scale command:
scale logdb;
scale('lock', [1e-5, 1e8, 1e-9, 1e9]);
The scale is locked, and the user may not unlock it. In the example above, note also that a single string argument can be written without quote and parenthesis if it contains only letters and digits.
With an output argument, scale returns the current scale as a vector [xmin,xmax,ymin,ymax]. If the scale is not fixed, the vector is empty. If only the horizontal scale is set, the vector is [xmin,xmax]. During a mouse drag, both the x and y are fixed. The values returned by scale reflect the zoom chosen by the user. They can be used to limit the computation of data displayed by plot to the visible area.
Here are some suggestions for the most usual graphics:
| Time response | (default linlin is fine) |
| Bode mag | scale logdb |
| Bode phase | scale loglin |
| D bode mag | scale('lindb/logdb',[0,pi/Ts]) |
| D bode phase | scale('linlin/loglin',[0,pi/Ts]) |
| Poles | scale equal |
| D poles | scale('equal',[-1,1,-1,1]) |
| Nyquist | scale('equal',[-1.5,1.5,-1.5,1.5]) |
| Nichols | scale lindb |
Use of scale to display a sine in the visible x range:
scale([0,10]); % default x range between 0 and 10
sc = scale; % maybe changed by the user (1x2 or 1x4)
xmin = sc(1);
xmax = sc(2);
x = xmin + (xmax - xmin) * (0:0.01:1);
% 101 values between xmin and xmax
y = sin(x);
plot(x, y);
Change the scale displayed in axis ticks and labels.
scalefactor(f) f = scalefactor
scalefactor(f) sets the factor used to display the ticks and the labels. Its argument f can be a vector of two real positive numbers to set separately the x axis and the y axis, or a real positive scalar to set the same factor for both axis. The normal factor value is 1, so that the ticks correspond to the graphical contents. With a different factor, the contents are displayed with the same scaling, but the ticks and labels are changed as if the graphical data had been scaled by the factor. For instance, you can plot data in radians (the standard angle unit in LME) and display ticks and labels in degrees by using a factor of 180/pi.
With an output argument, scalefactor gives the current factors as a 2-elements vector.
Display the sine with a scale in degrees:
phi = 0:0.01:2*pi; plot(phi, sin(phi)); scalefactor([180/pi, 1]);
Display text in a figure.
text(x, y, string) text(x, y, string, justification) text(..., font)
With three arguments, text(x,y,string) displays a string centered at the specified position. An optional fourth argument specifies how the string should be aligned with respect to the position (x,y). It is a string of one or two characters from the following set:
| Char. | Alignment |
|---|---|
| c | Center (may be omitted) |
| l | Left |
| r | Right |
| t | Top |
| b | Bottom |
For instance, 'l' means that the string is displayed to the right of the given position and is centered vertically, and 'rt', that the string is to the bottom left of the given position.
An optional trailing argument specifies the font, size, type face, and color to use. It is a structure which is typically created with fontset.
A line is drawn between (-1,-1) and (1,1) with labels at both ends.
plot([-1,1], [-1,1]); text(-1,-1, 'p1', 'tr'); text(1, 1, 'p2', 'bl');
Text with font specification:
font = fontset('Font', 'Times', ...
'Bold', true, ...
'Size', 18, ...
'Color', [1,0,0]);
text(1.1, 4.2, 'Abc', font);
Subplot title.
title(string)
title(string) sets or changes the title of the current subplot.