Produces perspective views of a two-way arrays of numbers.
Options
TITLE = text |
General title; default * |
|---|---|
WINDOW = scalar |
Window number for the plots; default 1 |
KEYWINDOW = scalar |
Window number for the key (zero for no key); default 2 |
ELEVATION = scalar |
The elevation of the viewpoint relative to the surface; default 25 (degrees) |
AZIMUTH = scalar |
Rotation about the horizontal plane; the default of 225 degrees ensures that, with a square matrix M, the element M$[1;1] is nearest to the viewpoint |
DISTANCE = scalar |
Distance of the viewpoint from the centre of the grid on the base plane; default * gives a distance of 100 times the maximum of the x-range and the y-range |
ZSCALE = scalar |
defines the scaling of the z-axis relative to the horizontal (x-y) axes; default 1 |
SCREEN = string token |
Whether to clear the screen before plotting or to continue plotting on the old screen (clear, keep); default clea |
KEYDESCRIPTION = text |
Overall description for the key; default * |
ENDACTION = string token |
Action to be taken after completing the plot (continue, pause); default * uses the setting from the last DEVICE statement |
Parameters
GRID = identifier |
Pointer (of variates representing the columns of a data matrix), matrix or two-way table specifying values on a rectangular grid |
|---|---|
PEN = scalar |
Pen number to be used for the plot; default 1 |
PENFILL = scalar or variate |
Pen number(s) defining how to fill the areas between contours (0 or * leaves the areas in the background colour); default 3 |
PENMESH = scalar |
Pen number to use to draw the mesh (omitted if set to 0 or *); default 1 |
PENSIDE = scalar |
Pen number to use to shade the sides of the surface (omitted if set to 0 or *); default * |
NCONTOURS = scalar |
Number of contours; default 10 |
CONTOURS = variate |
Positions of contours |
INTERVAL = scalar |
Interval between contours |
DESCRIPTION = text |
Annotation for key |
Description
The DSURFACE directive produces a perspective (or conical) projection of a surface, showing the view from a particular viewpoint. The surface is represented by a grid of z-values or heights. The grid can be a rectangular matrix, a two-way table or a pointer to a set of variates; the y-dimension is represented by the rows of the structure and the x-dimension by the columns. In each case there must be at least three rows and three columns of data (after allowing for any restrictions on a set of variates). Missing values are not permitted; that is, only complete grids can be displayed. If the grid is supplied as a table with margins, these will be ignored when plotting the surface.
The position of the viewpoint is specified in polar coordinates, using the options ELEVATION, DISTANCE and AZIMUTH. These define the angle of elevation, in degrees, above the base plane of the surface, distance from the centre of this plane, and angular position relative to the vertical z-axis, respectively. The default settings of ELEVATION, DISTANCE and AZIMUTH have been chosen to produce a reasonable display of most surfaces; but if, for example, some parts of the surface are obscured by high points they can be modified to obtain a better view. Altering the value of AZIMUTH will, in effect, rotate the surface in the horizontal plane about a vertical axis drawn through the centre of the grid; the default value of 225 degrees ensures that the element in the first row and column of the grid is at the corner nearest the viewpoint. Small values of DISTANCE produce a perspective view; larger values, like the default of 100 times the maximum of the x-range and the y-range, effectively put the viewpoint at infinity to produce an “orthographic parallel projection”.
The ZSCALE option specifies a scaling factor for the z-axis (or vertical axis) of the plotted surface. Generally values between 0.5 and 2.0 are most successful; large values result in a flatter surface, while smaller values produce a steep surface, accentuating changes in the data.
The TITLE, WINDOW, SCREEN and ENDACTION options are used to specify a title, the plotting window, whether the screen should be cleared first, and whether there should be a pause once the plotting is finished; as in other graphics directives (see, for example, DGRAPH). Similarly, the KEYWINDOW and KEYDESCRIPTION options and the DESCRIPTION parameters allow a key to be defined, if feasible for these plots with the current graphics device.
The PEN parameter specifies the pen to be used to plot the surface (by default, pen 1). The PEN directive can be used to modify the colour and the thickness of the pen, but the other attributes of the pen are ignored.
The NCONTOURS, CONTOURS and INTERVAL parameters control the contours drawn on the surface, if these are available on the current graphics device. The first possibility is to define the contours explicitly using the CONTOURS parameter. Alternatively, if CONTOURS is unset, INTERVAL can set the required interval between each contour. Or, if both CONTOURS and INTERVAL are unset, NCONTOURS defines the required number of lines. Genstat then partitions the range of data values accordingly to give NCONTOURS evenly-spaced contours (or fewer contours if there are insufficient distinct grid values).
The PENFILL parameter defines how to shade the areas between the contours. If this is set to a scalar, the shades are defined in increasing intensities of the colour of the specified pen. Alternatively, if PENFILL is set to a variate of length two, the pens are taken to define the shades at the minimum and maximum heights, and the other shades are interpolated between them. Finally, you can set PENFILL to a variate with more than two values, and the shading uses the pens in the order in which they are given in the variate (recycling if insufficient pens are defined for the total number of contours). The default is to use pen 3. However, if you set PENFILL to 0 or to a missing value, there will be no shading (that is, the areas between the contours will be in the background colour).
The PENMESH parameter specifies a pen to be used to draw a mesh on the surface. This consists of lines marking the points of the surface that lie above a rectangular grid on the xy plane. By default pen 1 is used, but if you set PENMESH to 0 or to a missing value the mesh is omitted.
The PENSIDE parameter defines the pen to use to shade the sides of the surface. There is no shading if this is set to 0 or a missing value, which is the default. The CFILL setting of the pen (see the PEN directive) specifies which colour is used.
Simple axes are drawn to indicate the directions in which x and y increase. The TITLE parameter of the XAXIS and YAXIS directives can be used to add further annotation.
Options: TITLE, WINDOW, KEYWINDOW, ELEVATION, AZIMUTH, DISTANCE, ZSCALE, SCREEN, KEYDESCRIPTION, ENDACTION.
Parameters: GRID, PEN, PENFILL, PENMESH, PENSIDE, NCONTOURS, CONTOURS, INTERVAL, DESCRIPTION.
Action with RESTRICT
DSURFACE takes account of restrictions on any of the variates in a GRID pointer.
See also
Directives: DBITMAP, DCONTOUR, DSHADE, D3HISTOGRAM, FRAME, XAXIS, YAXIS, ZAXIS, PEN, MATRIX, POINTER, TABLE.
Commands for: Graphics.
Example
" Example DSUR-1: Surface and shade plot of a trig function "
"Create data on a regular 101 x 101 grid for trig Function"
DELETE [REDEFINE=YES] N,X,Y,Z
SCALAR N; 101
MATRIX [ROWS=N; COLUMNS=1] X; VALUES=!(1...N)
& [ROWS=1; COLUMNS=N] Y; VALUES=!(1...N)
CALCULATE Z = 2 * SIN(SQRT(((X - (N+1)/2) *+ ROW1(N)/6)**2\
+ (COL1(N) *+ (Y - (N+1)/2) / 6)**2))**2\
/(4 + SQRT(((X - (N+1)/2) *+ ROW1(N) / 10)**6\
+ (COL1(N) *+ (Y - (N+1)/2) / 10)**6))
" Draw a surface plot "
FRAME [RESET=yes] 3
XAXIS [RESET=yes] 3; TITLE = 'X'
YAXIS [RESET=yes] 3; TITLE = 'Y'
ZAXIS [RESET=yes] 3; TITLE = 'Z'
PEN [RESET=yes] 3
DSURFACE [TITLE='Surface plot of a trig function'; WINDOW=3; KEY=0] Z; PEN=3
" Draw a shade plot "
FRAME [RESET=yes] 1
XAXIS [RESET=yes] 1; TITLE = 'X'
YAXIS [RESET=yes] 1; TITLE = 'Y'
PEN [RESET=yes] 1; COLOUR='red'
PEN [RESET=yes] 2; COLOUR='blue'
DSHADE [TITLE='Shade Plot of trig function'; GRID=*] Z; PEN=!(1,2)