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