SHADE_SURF Procedure

Creates a shaded surface representation of a regular or nearly regular gridded surface, with shading from either a light source model or from a specified array of intensities.

Usage

SHADE_SURF, z[, x, y]

Input Parameters

z—A two-dimensional array containing the values that make up the surface. If x and y are supplied, 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.

x—A vector or two-dimensional array specifying the x-coordinates for the contour surface. If x is a vector, each element of x specifies the x-coordinate for a column of z.

For example, 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_ijspecifies the x-coordinate for z_ij).

y—Vector or two-dimensional array specifying y-coordinates for contour surface. If a vector, each element of y specifies the y-coordinate for a row of z.

For example, 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).

Keywords

Image—Name of variable into which the image containing shaded surface is stored. If this keyword is omitted, the image is displayed but not saved.

Max_Img_Size—For devices with scalable pixels (e.g., postscript), this keyword sets the largest allowed image size created internally to render the shaded surface. Larger values will result in a better quality image but at a cost of greater memory use and larger file size. The mimimum value is 100 (100x100), which will generally result in a poor-quality image. (Default: 400)

Shades—An array expression, of the same dimensions as z, containing the color index at each point. The shading of each pixel is interpolated from the surrounding Shades values. For most displays, this parameter should be scaled into the range of bytes. If this keyword is omitted, light source shading is used.

Other keywords are listed below. For a description of each keyword, see Graphics and Plotting Keywords.

Ax	Font	Thick	[XYZ]Thick
Az	Gridstyle	Tickformat	[XYZ]Tickformat
Background	Noclip	Ticklen	[XYZ]Ticklen
Channel	Nodata	Title	[XYZ]Tickname
Charsize	Noerase	[XYZ]Charsize	[XYZ]Ticks
Charthick	Normal	[XYZ]Gridstyle	[XYZ]Tickv
Clip	Position	[XYZ]Margin	[XYZ]Title
Color	Save	[XYZ]Minor	ZValue
Data	Subtitle	[XYZ]Range
Device	T3d	[XYZ]Style

Discussion

SHADE_SURF is similar to the SURFACE procedure. Given a regular or near-regular grid of elevations, SHADE_SURF produces a shaded surface representation of the data with the hidden surfaces removed.

If the graphics output device has scalable pixels (e.g., PostScript), then the output image is scaled so that its largest dimension is less than or equal to 400. Use the Max_Img_Size keyword to increase this size.

When outputting to PostScript devices, the default for the Background keyword is white (index 255), rather than !P.Background.

Use the SET_SHADING procedure to control the direction of the light source and other shading parameters.

Note:

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.

If the X,Y grid is not regular or nearly regular, errors in hidden line removal will likely occur. In this case, you should use the SHADE_SURF_IRR procedure.

SHADE_SURF is not supported on Tektronix terminals or the 4510 Rasterizer. If you try to display shaded image on such a device, PV‑WAVE may abort. This is because of a limitation in the range of image coordinates available on Tektronix devices. SHADE_SURF is also unsupported on VT240 terminals.

Example 1

This example uses SHADE_SURF to display a shaded surface representation of the function:

where:

The results are shown in Shaded Surface with Title.

; Create 101-element vector of x-coordinates

; such that -10 < x < 10.

x = FINDGEN(101)/5 - 10

; Make vector of y-coordinates same as vector of x-coordinates.

y = x

; Create a 101-by-101 array to hold the function values.

z = FLTARR(101, 101)

; Insert the function values into z. Note that z is filled

; columnwise instead of elementwise.

FOR i=0L, 100 DO BEGIN $

   z (i, *) = x(i)*SIN(y) + y*COS(x(i)) - SIN(0.25*x(i)*y)

; Display the shaded surface. The Ax keyword is used to

; specify the desired angle of rotation about the x-axis.

; The XCharsize, YCharsize, and ZCharsize keywords are used

; to enlarge the characters used to annotate the axes.

SHADE_SURF, z, x, y, Ax=50, XCharsize=2, $

   YCharsize=2, ZCharsize=2

; Place a title in the window. Note that the CURSOR

; procedure with the Device keyword was used to locate

; the proper position for the title.

XYOUTS, 110, 463, 'f(x, y) = x*sin(y) + y*cos(x) - ' + $

   'sin(x*y)/4)', Charsize=1.5, /Device

Shaded Surface with Title

Example 2

Users often wish to store the data that describes a surface in a file. Each row of data in the file is a point on the surface so there are three columns of data in the file. The first column contains x-coordinates of the points, the second column contains y-coordinates of the points, and the third column contains z-coordinates of the points.

This example creates data describing the surface defined by the function: