Reads the locations of points from an interactive graphical device.
Options
PRINT = string tokens |
What to print (data, summary); default summ |
|---|---|
CHANNEL = scalar |
Number of the graphics device from which to read; default * takes the current graphics device |
WINDOW = scalar |
Window from which to read; default 1 |
CURSORTYPE = scalar |
Type of cursor; default 1 |
SETNVALUES = string token |
Whether to set number of values of structures from the number of values read (yes, no); default no causes the number of values to be set only for structures whose lengths are not defined already |
ENDACTION = string token |
Action to be taken after completing the plot (continue, pause); default * uses the setting from the last DEVICE statement |
Parameters
Y = variates |
Variate to receive the y-values that have been read |
|---|---|
X = variates |
Variate to receive the x-values that have been read |
YGIVEN = variates |
Y-coordinates of points that may be located on the graph |
XGIVEN = variates |
X-coordinates of points that may be located |
SAVESET = variates |
Unit numbers of the located points |
PEN = scalars |
Pen number to use to echo points; default 0 |
YSAVE = variates |
Variate to receive the y-coordinates of the located points |
XSAVE = variates |
Variate to receive the x-coordinates of the located points |
Description
The DREAD directive allows you to input information about the positions of points on interactive graphical terminals. The exact details of how this directive operates will vary slightly from one system to another, so this section attempts to outline the basic principles involved. If you encounter any difficulties using DREAD you should refer to the Users’ Note supplied with your version of Genstat.
When you type DREAD, a cursor should appear on the graphics screen. This can be moved to the chosen position by using the cursor keys or a mouse; the coordinates of this point can then be read by pressing a key or mouse button (normally the left hand mouse button). The cursor can then be moved to another position to read the next point. You can use graphical input within any window that contains a graph or contour plot, but you cannot input data from an “empty” window or one containing other forms of graphical output. In addition you can identify particular points from those plotted on an existing graph and you can mark the points that you have read.
The CHANNEL and WINDOW options are used to specify the device and the window from which the information is to be read; the default is to read from window 1 of the current device. The values that are read are converted to the scale of the data that was previously plotted in that window, and are then stored in the pair of variates specified by the Y and X parameters.
Any number of points may be read in one DREAD statement. If the required number of points is known in advance, the Y and X variates can be declared with the appropriate length, and the input will terminate automatically when sufficient points have been read. Alternatively, if the lengths of the variates have not been defined in advance, points are read until you terminate the input, and the variates are defined accordingly. This action can be requested explicitly by setting option SETNVALUES=yes; the existing variate lengths are then ignored and points are read until the input is terminated. Graphical input can usually be terminated in two ways, either by pressing a mouse button (usually the right button) or a key that has been specifically defined for this purpose, or by attempting to read a point lying outside the current axes. In case of difficulty you should refer to the Users’ Note which will explain how to terminate the input on specific devices. The final point read as a terminator is not included in the Y and X variates. If you try to terminate input prematurely when a set number of values is to be read, the corresponding Y and X values are set to missing values.
The PRINT option of DREAD is similar to the PRINT option of READ. Putting PRINT=data lists the y- and x-values of the points that have been read, while PRINT=summary generates the usual summary of mean, minimum, maximum and number of values.
Several types of cursor may be available; again this will depend on the graphics device. The cursor is selected by setting the CURSORTYPE option to an integer between 1 and 10. Normally cursors 1, 2 and 3 are different graphics cursors; for example, large cross-hair, arrow and small cross. Cursors 4 and 5 may be set up to provide special functions called rubber-band and rubber-rectangle.
A rubber-band cursor works by reading one point in the normal way (as if CURSORTYPE was set to 1). This defines an anchoring point for a line whose other end is attached to the cursor. As you move the cursor, the line will change direction and contract or expand, but always linking the fixed point to the current cursor position: hence the term “rubber-band”. When you read the next point this will become the anchor point for a new rubber-band segment which you use whilst locating a third point, and so on until the required number of points have been read.
The rubber-rectangle works in a similar way, with the first point being read with a normal cursor. This defines the fixed point and the cursor is now regarded as being attached to the diagonally opposite corner of a rectangle which will contract and expand as you move the cursor around the screen. Reading the second point terminates the input; with a rubber-rectangle cursor Genstat will always read exactly two values, ignoring the SETNVALUES option and any predefined length of Y and X.
The rubber-band and rubber-rectangle types of cursors may not be available on all devices, in which case setting CURSORTYPE to 4 or 5 will use one of the simpler cursors. However, setting CURSORTYPE to 5 will always read just two points, regarded as being diagonally opposite corners of a rectangle, whether or not the rubber-rectangle appears on the screen.
Some devices may have more than one method of manipulating the graphics cursor, for example by use of a joystick or mouse. In this case, cursor-types 1 to 5 will be set up as described above for the joystick, say, and types 6 to 10 will be the same types of cursor but controlled by the mouse. Usually, however, there will be only one method of control, in which case cursor-types 6 to 10 will be the same as types 1 to 5.
The PEN parameter of DREAD can be used to specify a pen which will be used to plot each point as its position is read. The various attributes of this pen determine how the points are plotted; these can be modified, in the usual way, using the PEN directive. If the pen method is set to line, monotonic, open or closed, then straight line segments will be drawn between the points; otherwise just the points themselves are plotted. If the points are to be joined by lines and a rubber-rectangle cursor is being used, the rectangle will be drawn rather than the diagonal line. If labels are set for the pen, they will be used in turn to mark the points as they are read; if the number of points exceeds the number of labels the labels will be recycled.
The YGIVEN and XGIVEN parameters allow you to identify points that have been plotted in an existing graph. They should be set to the y- and x-variates that were plotted on the graph. Each point that is read by DREAD is then located within this pair of variates, by finding the original point that is physically nearest to the new point, ignoring any differences in the scales of the y- and x-values. The unit number of the located points can be saved in a variate specified by the SAVESET parameter, and their coordinates in a pair of variates supplied by the YSAVE and XSAVE parameters. The length of the variates is defined in the same way as for the Y and X variates. The variates saved by YSAVE and XSAVE contain the actual coordinates of the plotted points that were selected by DREAD; whereas the Y and X variates contain the coordinates of the exact position of the cursor. The SAVESET variate indicates the unit numbers of the selected points. This information could be used, for example, in CALCULATE or RESTRICT statements to refer to the units that have been identified on the graph. For example,
DREAD U; V; YGIVEN=Y; XGIVEN=X; SAVESET=SS
RESTRICT Y,X; .NOT.EXPAND(SS; NVALUES(X))
would have the effect of excluding the points identified by DREAD; in this example the exact cursor locations recorded in U and V are not of interest.
When the PEN parameter is being used to mark the points that are read, you may want to pause at the end of the read so that you can inspect the modified graph. This is controlled by the ENDACTION parameter.
Options: PRINT, CHANNEL, WINDOW, CURSORTYPE, SETNVALUES, ENDACTION.
Parameters: Y, X, YGIVEN, XGIVEN, SAVESET, PEN, YSAVE, XSAVE.
See also
Directive: DEVICE.
Commands for: Graphics.