The SURFACE procedure draws a wire-mesh representation of a two-dimensional array projected into two dimensions, with hidden lines removed.

If the *
(X, Y)*
grid is not regular or nearly regular, errors in hidden line removal occur. The TRIGRID and TRIANGULATE routines can be used to interpolate irregularly-gridded data points to a regular grid before plotting.

If the T3D keyword is set, the 3D to 2D transformation matrix contained in !P.T must project the Z axis to a line parallel to the device Y axis, or errors will occur.

The surface lines may blend together when drawing large arrays, especially on low or medium resolution displays. Use the REBIN or CONGRID procedure to resample the array to a lower resolution before plotting.

The two-dimensional array to be displayed. If *
X*
and *
Y*
are provided, the surface is plotted as a function of the (*
X*
, *
Y*
) locations specified by their contents. Otherwise, the surface is generated as a function of the array index of each element of *
Z*
.

This argument is converted to single-precision floating-point before plotting. Plots created with SURFACE are limited to the range and precision of single-precision floating-point values.

A vector or two-dimensional array specifying the X coordinates of the grid. If this argument is a vector, each element of *
X*
specifies the X coordinate for a column of *
Z*
(e.g., ```
X[0]
```

specifies the X coordinate for ```
Z[0,*]
```

). If *
X*
is a two-dimensional array, each element of *
X*
specifies the X coordinate of the corresponding point in *
Z*
(*
X*
_{
ij}
specifies the X coordinate for *
Z*
_{
ij}
).

This argument is converted to single-precision floating-point before plotting.

A vector or two-dimensional array specifying the Y coordinates of the grid. If this argument is a vector, each element of *
Y*
specifies the Y coordinate for a row of *
Z*
(e.g., ```
Y[0]
```

specifies the Y coordinate for ```
Z[*,0]
```

). If *
Y*
is a two-dimensional array, each element of *
Y*
specifies the Y coordinate of the corresponding point in *
Z*
(*
Y*
_{
ij}
specifies the Y coordinate for *
Z*
_{
ij}
).

This argument is converted to single-precision floating-point before plotting.

This keyword specifies the angle of rotation, about the X axis, in degrees towards the viewer. This keyword is effective only if !P.T3D is not set. If !P.T3D is set, the three-dimensional to two-dimensional transformation used by SURFACE is taken from the 4 by 4 array !P.T.

The surface represented by the two-dimensional array is first rotated, AZ (see below) degrees about the Z axis, then by AX degrees about the X axis, tilting the surface towards the viewer (AX > 0), or away from the viewer.

The AX and AZ keyword parameters default to +30 degrees if omitted and !P.T3D is 0.

The three-dimensional to two-dimensional transformation represented by AX and AZ, can be saved in !P.T by including the SAVE keyword.

This keyword specifies the counterclockwise angle of rotation about the Z axis. This keyword is effective only if !P.T3D is not set. The order of rotation is AZ first, then AX.

The color index used to draw the bottom surface. If not specified, the bottom is drawn with the same color as the top.

A keyword flag which if set causes SURFACE to only draw lines across the plot perpendicular to the line of sight. The default is for SURFACE to draw both across the plot and from front to back.

Set this keyword to produce stacked histogram-style plots. Each data value is rendered as a box covering the XY extent of the cell and with a height proportional to the Z value.

If the *
X*
and *
Y*
arguments are specified, only *
N*
_{
x}
-1 columns and *
N*
_{
y}
-1 rows are drawn. (This means that the last row and column of array data are not displayed.) The rectangular area covered by *
Z*
[*
i*
, *
j*
] is given by *
X*
[*
i*
], *
X*
[*
i*
+1], *
Y*
[*
j*
], and *
Y*
[*
j*
+1].

Set this keyword to draw only the lower surface of the object. By default, both surfaces are drawn.

The maximum value to be plotted. If this keyword is present, data values greater than the value of MAX_VALUE are treated as missing and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. (See Special Floating-Point Values for more information on IEEE floating-point values.)

The minimum value to be plotted. If this keyword is present, data values less than the value of MIN_VALUE are treated as missing and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. (See Special Floating-Point Values for more information on IEEE floating-point values.)

Set this keyword to save the 3D to 2D transformation matrix established by SURFACE in the system variable field !P.T. Use this keyword when combining the output of SURFACE with additional output from other routines in the same plot.

When used with AXIS, the SAVE keyword parameter saves the scaling parameters established by the call in the appropriate axis system variable, !X, !Y, or !Z. This causes subsequent overplots to be scaled to the new axis.

- To display a two-dimensional array using SURFACE, and to then superimpose contours over the surface (this example assumes that !P.T3D is zero, its default value.), enter the following commands:

SURFACE, Z, /SAVE *;
Make a surface plot and save the transformation.*

CONTOUR, Z, /NOERASE, /T3D *;
Make contours, don't erase, use the 3D to 2D transform placed in !P.T by SURFACE.*

To display a surface and to then display a flat contour plot, registered above the surface:

SURFACE, Z, /SAVE *;
Make the surface, save transform.*

CONTOUR, Z, /NOERASE, /T3D, ZVALUE=1.0 *;
Now display a flat contour plot, at the maximum Z value (normalized coordinates).*

You can display the contour plot below the surface with by using a ZVALUE of 0.0.

This keyword allows user-specified coloring of the mesh surfaces. Set this keyword to an array that specifies the color index of the lines emanating from each data point toward the top and right.

**CAUTION: **
When using the SHADES keyword on True Color devices, we recommend that decomposed color support be turned off, by setting DECOMPOSED=0 for

DEVICE
.

This keyword represents a Z-value at which to draw a skirt around the array. The Z value is expressed in data units. The default is no skirt.

If the skirt is drawn, each point on the four edges of the surface is connected to a point on the skirt which has the given Z value, and the same X and Y values as the edge point. In addition, each point on the skirt is connected to its neighbor.

Set this keyword to draw only the upper surface of the object. By default, both surfaces are drawn.

This keyword specifies the placement of the Z axis for the SURFACE plot.

By default, SURFACE draws the Z axis at the upper left corner of the axis box. To suppress the Z axis, use ```
ZAXIS=-1
```

in the call. The position of the Z axis is determined from the value of ZAXIS as follows: 1 = lower right, 2 = lower left, 3 = upper left, and 4 = upper right.

See , Graphics Keywords , for the description of graphics and plotting keywords not listed above. BACKGROUND

D = DIST(30) *;
Create a simple dataset to display.*

SURFACE, D *;
Plot a simple wire-mesh surface representation of D.*

SURFACE, D, SKIRT=0.0, TITLE = 'Surface Plot', CHARSIZE = 2

*;
Create a wire-mesh plot of D with a title and a "skirt" around the edges of the dataset at Z=0.*