Plotting of data
This chapter will acquaint you with some of the capabilities of the plot_xy
unit for creating 2-dimensional data plots. You will learn
How to use
the plot_xy unit for plotting of data
The example#1 illustrates
a plot in which two different drawing layers are superimposed:
(i) a connected random path to which each execution "Step" adds
another line segment (sequential plotting), and
(ii) a "cloud" of 10 points whose positions are specified as the elements
of a 20-dimensional vector (simultaneous plotting).
Select the plot_xy
unit's
'm'
field to see how the plot_xy unit has been configured for this.
The upper part of the dialog box determines rather obvious things, such
as a window name, size, position and axis ranges. The superimposed drawing
layers are specified in the middle part. Each line belongs to one "drawing
layer" of marker symbols (optionally connected into a path) and gives rise
to a separate input connector for their xy-position(s).
The first three colums specify color, shape and pixel size of the marker
symbols of a drawing layer, the button in the last column determines whether
each execution step adds a single marker (xy pnt) to the layer (incremental
drawing), or draws a new set of markers for that layer, discarding any
previous markers in that layer (simultaneous drawing).
For each incremental drawing layer, the associated input connector is
a 2d scalar float array (expecting the xy coordinates of
the to-be-added marker point). For each simultaneous drawing layer, the
associated input connector is a float vector input of dynamic dimension
that will determine the number of marker points that are drawn (each pair
of consecutive elements in the vector will be taken as a coordinate pair
of a marker point; if the total number of elements is odd, the last element
will remain unused).
How to connect plotted
points by lines
To connect successive markers by lines (of the same color), specify as
symbol type a negative value (in this case, the absolute value will
select the symbol type). To connect markers by lines of a different color
requires either to first connect to the destination point in the desired
line color, and then to specify the destination point again, but now for
the marker in its different color (the next example#2
will illustrate this). Alternatively, you can to use two separate layers,
one for the markers of color 1, and one for connected points (marker type
-1 for points) of color 2.
How
to control color, shape and size of plotted symbols
In addition to the "xy pnt" and "xy vec"
modes there are also the modes "xycts pnt" and "xycts
vec".
The "xycts pnt" mode is analogous to "xy pnt", but the
input connector now has 5 pins and expects xcoordinate, y-coordinate,
color, type of symbol and size of symbol for the to-be-added marker. By
specifying a suitable series of 5-tuples, you can thus draw any sequence
of symbols, with any subset of line connections, even of a different (and
varying) color (see example#2).
The "xycts vec" mode is analogous to "xy vec" and uses
the elements of its associated dynamic float vector input connector in
blocks of five to determine the above attributes for the to-be-added marker
points (ignoring trailing element(s) if the total number is not an integral
multiple of 5). Example#2
has already used this mode within its second plot_xy unit (that
draws the same data as the first, but from the entire data vector in parallel
fashion). The example#3
illustrates how to use the "xycts vec" mode to plot an array of
markers whose shape, size and symbol type vary as a function of their position.
How to control
tick marks and axis labels
How to control plot margins
How to add text to a plot
All this can be achieved by specifying an "option string" in the
"Further
Options" entry field. An option string consists of tokens introduced
with a percent '%' character, followed by up to four colon-separated
numerical parameters and ended by an "option character". The relevant
option characters for tick marks, plot margins and addition of text are
't',
'M' and '=', respectively, and their parameters are explained
in the creation dialog window of the plot_xy unit. The
example#4
illustrates their use in a few differently configured plot_xy units.
How to control scaling
The parameter window of the plot_xy unit allows to rescale one or
both axis directions so that all drawn data points fit into the display
(the rescaling will take effect only after the window has been left with
"OK"). If a dynamic scaling is desired, you can (in the creation dialog
box) request an additional "scaling connector" with 2 values (min
and max limit for dynamic scaling of one axis direction) or with 4 values
(xy coordinates of 2 diagonally opposed points of the to-be-displayed
data rectangle).
Example#5 illustrates
the use of scaling inputs for viewing a point cloud (how the input_window
unit works will be explained in the next
chapter).
How to draw
into a plot with other NST-units
In order to draw into the plot of a plot_xy unit, you must specify
a plot window title in the creation dialog box. Then you can use one or
several
draw_sym,
draw_str
and draw_pix units to draw
a group of symbols, a string or a pixel bitmap into the plot window, specifying
the target window title as a creation parameter to the draw_* unit(s).
The desired plot location and further properties of the to-be-drawn marker
symbol(s), text string or bitmap have to be specified at the input connector(s)
of the draw_* unit(s). The drawing position can be given in pixels
or in data units, if autoscaling mode is used.
How to query
point positions with the mouse
The mouse_xy unit allows
to query a location in a plot_xy window. It works analogously as
the draw_sym unit (i.e.,
the target window must be specified by its window title), but instead of
a positional input it yields a positional output (the mouse xy coordinates
in pixels or data units, again depending on the chose mode). Further settings
allow to specify blocking modes and to return information about mouse button
presses (details will be explained in the later chapter Using
the mouse).
In example#6
, a
for op executes a mouse_xy
unit repeatedly to query positions in a plot_xy window. At each
left mouse
button press, the (x,y) position of the mouse cursor is read
out (available at the first output connector of mouse_xy) and used
by the draw_sym and draw_str units to draw a marker and the
coordinate values at the queried position. Note that the "autoscale"
option
in the mouse_xy, draw_sym and draw_str units ensures that
(x,y)
is always given in data coordinates. The break_unit
allows to leave the loop with the right mouse button. Note also the use
of the %I options in draw_sym and draw_str to "undraw"
each previous draw.
If you set "Nowait" mode in the mouse_xy unit, the marker
and printed position will follow the cursor continuously.
NOTE: the use of loops is not the best way of writing interactive
programs. Later we shall see how to use callbacks for this
purpose (the mouse_xy unit supports these, but we will explain
that in a later chapter).
How to speed up plotting
Incremental plots of very many data points may be slow. If the number of
to be plotted points is known beforehand to always be an (integral) multiple
of a larger number N, the plotting can be made in blocks of N, i.e., only
after N exec calls have accumulated will the the added points be made visible.
Additionally, one can request an automatic clear and restart of the plot,
whenever an additional point comes in.
Related plot units
The plot_vec unit and the
plot_series
unit are specialized variants of the plot_xy
unit, customized conveniently for the frequent task of plotting the data
in a vector (plot_vec) or a time series (plot_series). They
can be used in the same way as the plot_xy unit in conjunction with
the draw_* units and the mouse_xy unit.
Example#7 illustrates
the use of the plot_vec unit to display a brightness histogram for
a pixel image.
Example#8 illustrates
the use of the plot_series unit to display several superimposed
time series.