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)