NAME
plot_xy - make general two-dimensional data plot
PROTOTYPE
unitptr plot_xy( int n, char *windesc, char *fmt, float xmi, float xma, float ymi, float yma, unittype *dest)
ARGUMENTS
- int n
- number of plots to be superimposed. For each plot a separate input field of two pins will be created, and separate marker symbols with separate color and size can be defined (see below).
- char *windesc
- character string specifying title, position, and size of window. General format: "title xll yll width height", where title is an arbitrary sequence of characters not containing any white space and xll, yll, width, height specify the window location (lower left corner) and size in screen pixels.
- char *fmt
- `format string'' specifying how to plot (see below)
- float xmi
- minimal x-data value
- float xma
- maximal x-data value
- float ymi
- minimal y-data value
- float yma
- maximal y-data value
- unittype *dest
- host unit
INTERFACE OF CREATED UNIT:
- in_0[d0]:
- (input field 0) coordinate pair for plot 0
- in_1[d1]:
- (input field 1) coordinate pair for plot 1
- ...
- ...
- in_n-1[dn-1]:
- (input field n-1) coordinate pair for plot n-1
- CTL_in[]:
- control field. A value of zero disables the unit.
If option %S is specified, CTL_in[] will have four
scaling pins, defining a data rectangle
[xmin,ymin,xmax,ymax] onto which the plot area
shall be mapped.
SYNOPSIS:
Creates a unit for the simultaneous display of up to n
plots in a cartesian x-y-coordinate system.
Each call of exec_unit adds a marker symbol to each plot. These
markers are stored in an internal buffer so that the plot can
be redrawn at any time (but the buffer will also continue to
grow unless intervening NST_RESET, NST_INIT or NST_W_CLEAR
calls discard the stored points from time to time).
The save_unit/load_unit routines allow to save/retrieve
a plot to/from a data file.
DESCRIPTION:
The location each added
marker symbol is given by the pair of coordinate values specified
at the corresponding input field at the time of the exec_unit-call.
Additional functions are available by calling ctrl_unit(cmode,u) (see below).
The type and various options for the plot can be specified
with the format string fmt. fmt must
contain a sequence of control tokens of the form %f1:f2:f3:f4m, where
f1..f4 are up to 4 argument parameters, and m is a control letter.
Each
token %f1:f2:f3m specifies one plot. Parameters f1, f2 and f3 specify
a color f1, the choice of a marker symbol f2
and a marker symbol size f3.
If a control field specifies fewer than
four parameters, suitable default values will be assumed.
The plots will be associated with input fields 0,1...n
in the order of the occurrence of their %m-control fields in fmt.
To specify values f2, f2
for the number of tick marks to be used on each axis, a control field
%f1:f2t can be used. If either of f1, f2 is specified as
negative, drawing of the corresponding axis is suppressed.
For a instead of m, the 2D-input field will be replaced by
a 5d-input field with pins for x-value, y-value, color,
marker type and size.
To change the width of the margin between the plot area and the
window borders to a width of f pixels, specify the control field
%fM.
Values for f1 are:
- 0:
- invisible
- 1:
- foreground color (default: white)
- 2:
- red
- 3:
- green
- 4:
- blue
- 5:
- yellow
- 6:
- magenta
- 7:
- cyan
- 8:
- white (always)
- 9:
- black
To redefine foreground and background color, see OPTIONS below.
Values for f2 are:
- 1:
- single point
- 2:
- square
- 3:
- diamond
- 4:
- triangle
- 5:
- cross mark
- 6:
- plus mark
- 7:
- star burst
- 8:
- circle
- 9:
- empty histogram box of height y
- 10:
- filled histogram box of height y
- 11:
- error cross (size = (x,y), position is (x,y) of previous graph)
If y=0, only horizontal bar is drawn, if x=0, only vertical bar is drawn.
- 13:
- filled histrogram box of width x (note that f2=12 is internally used
for the drawing of error crosses)
If instead the negative of these values is specified, the drawn
symbols will be connected by lines of the same color.
In particular, the value f2 = -1
allows the drawing of arbitrary polygons.
Values for f3 are the size in pixels of the marker symbol to
be used. If marker 0 (single pixel) is chosen, the value of f3 is
disregarded. If f3<0, the positive value -f3 is interpreted
as the size of the symbol relative to the width of the plot window
(taken as 1000 units wide). I.e, f3=-50 specifies a width of
5 percent of the total window width.
FURTHER OPTIONS:
fmt allows to specify a number of further options that affect drawing
(in the following, f is an integer)
- %Font=name
- font to be used for drawing text into the window
name is either an X11 font name. The integers 0,1,2,3
are recognized as a shorthand for tiny, small, medium and
large fonts.
- %f:gC
- redefine foreground to color f, background to color g,
(here, 0 and 1 always have the meanings of black and white)
- %fC
- redefine foreground to color f. %0C additionally chooses
white background, i.e., yields black on white.
- %C
- redefine background (foreground) color to NST window (text) color
- %a:b:c:dM
- set left, right, lower and upper margins between
plot area and window borders to a,b,c
and d pixels width, respectively.
- %aN
- specify the maximal nr a of point groups (a point group encompasses
all points taken in during one exec_call) that are saved to or
loaded from the data file used by the load_unit and save_unit
calls. The default is a=2000, i.e., the plot results of up to
maximally the 2000 most recent invocations of the unit are saved
or restored to/from file (note that the number of points that can be kept
in memory is not limited by this limit).
- %fr
- Auto-Reset mode: display f data points in frontbuffer.
At the next data point, clear display and display the new point
as the first point of a new cycle
of plotting f points
- %fR
- dito, but the f points are collected in the backbuffer.
At the f+1 -th point, buffers are switched, the new
backbuffer cleared and the f+1-th point inserted for
a new cycle as
the first new point in the backbuffer.
- %fd
- deferred drawing. Always accumulate d points (.exec_calls)
before updating the plot. Useful to reduce overhead for
speeding up drawing.
- %X
- explicit X-scaling: if this option is given, the control input pin
will have two pins, allowing to specify the x-range for the plot.
- %Y
- explicit Y-scaling: if this option is given, the control input pin
will have two pins, allowing to specify the y-range for the plot.
If both, %X and %Y are specified, the control input pin will have four
pins, for specifying the x- and y range of the plot by a pair
of two points (i.e., the expected input is (x1,y1,x2,y2), but
the values x1,x2 and y1,y2 need not be ordered in increasing size).
- %f1:f2S
- Auto-Shift mode: each exec-call shifts all buffered points
by -f1, draws them into the (cleared) backbuffer, and
switches buffers. At most f2 points are buffered.
- %0=ThisIsText
- add label for x-axis
- %1=ThisIsText
- add label for y-axis
- %x:y:c=ThisIsText
- add label at relative position (x,y)
(range is 0..1000 along each window side).
ThisIsText must be a single token, but the tilde char
can be used to represent a space.
If :c is omitted, the default will be to use the
center of the label as hot spot.
- %x:y:clThisIsText
- similar to previous option:
add a label ThisIsText at position (x,y).
ThisIsText must be a single token, but the tilde char
can be used to represent a space.
If x>=0, it is horizontal offset to left margin in pixels,
if x<0, -x is considered as a relative horizontal position
with 0=entire left, 1000=entire right.
y is interpreted analogously. The value of c determines
the location of a `hot spot'' relatively to the text:
7 6 5
0ThisIsText4 8 = hot spot at center
1 2 3
Note: to add text at locations given in data coordinates,
use the .draw\_str unit.
- %a:b:c:dt tick marks:
- at least .a and .b labelled tick marks
for the x and y axis, respectively, and a total number
of at least c and d finer subdivisions.
CONTROL MODES:
A call of ctrl_unit(iMode,u) with iMode one of the following
can be used to achieve a number of further operations:
- NST_W_PENUP
- interrupts the drawing of lines for the duration of a single
exec_unit-call. After this call,
the drawing of a connecting line will be suspended for the next
exec_call and automatically resume thereafter.
- NST_W_REDRAW
- redraw plot
- NST_W_CLEAR:
- clear plot (i.e. erase all stored data points)
- NST_W_RESCL
- rescale plot axis to fit all data points encountered so far
- NST_W_XRESCL
- as before, but restricted to x-axis
- NST_W_RESCL
- as before, but restricted to y-axis
- NST_W_RESTORE
- restore original scaling
- NST_W_CLOSE:
- make window disappear until next use
- NST_PLOT_XLOG:
- switch to logarithmic x-axis scaling
- NST_PLOT_XLIN:
- switch to linear x-axis scaling
- NST_PLOT_YLOG:
- switch to logarithmic y-axis scaling
- NST_PLOT_YLIN:
- switch to linear y-axis scaling
- NST_PLOT_BOX:
- draw four-sided axes
- NST_PLOT_NOBOX:
- draw two intersecting axes
SEE ALSO:
plot_vec, plot_series, draw_sym,
draw_str, draw_pix, draw_mesh, mouse_xy, view3d
FILE
/local/homes/rhaschke/nst7/man/../o.linx86//../nstsrc/nst_plot.c