Reads the locations of points from an interactive graphical device.
|What to print (
||Number of the graphics device from which to read; default
||Window from which to read; default 1|
||Type of cursor; default 1|
||Whether to set number of values of structures from the number of values read (
||Action to be taken after completing the plot (
||Variate to receive the y-values that have been read|
||Variate to receive the x-values that have been read|
||Y-coordinates of points that may be located on the graph|
||X-coordinates of points that may be located|
||Unit numbers of the located points|
||Pen number to use to echo points; default 0|
||Variate to receive the y-coordinates of the located points|
||Variate to receive the x-coordinates of the located points|
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.
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
Any number of points may be read in one
DREAD statement. If the required number of points is known in advance, the
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
X variates. If you try to terminate input prematurely when a set number of values is to be read, the corresponding
X values are set to missing values.
DREAD is similar to the
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
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.
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
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.
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
XSAVE parameters. The length of the variates is defined in the same way as for the
X variates. The variates saved by
XSAVE contain the actual coordinates of the plotted points that were selected by
DREAD; whereas the
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
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
V are not of interest.
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
Commands for: Graphics.