POLYSHADE Function

Reference Guide > P Routines > POLYSHADE Function

POLYSHADE Function

Constructs a shaded surface representation of one or more solids described by a set of polygons.

Usage

result = POLYSHADE(vertices, polygons)

result = POLYSHADE(x, y, z, polygons)

Input Parameters

vertices — A (3, n) array containing the x-, y-, and z-coordinates of each vertex. Coordinates may be in either data or normalized coordinates, depending on which keywords are present.

x, y, z — The x-, y-, and z-coordinates of each vertex may alternatively be specified as three individual array expressions; x, y, and z must all contain the same number of elements.

polygons — An integer or longword array containing the indices of the vertices of each polygon. The vertices of each polygon should be listed in counterclockwise order when observed from outside the surface. The vertex description of each polygon is a vector of the form [n, i0, i1, ... , in – 1], and the array polygons is the concatenation of the lists of each polygon.

For example, to render a pyramid consisting of four triangles, polygons will contain 16 elements, made by concatenating four 4-element vectors of the form [3, V0, V1, V2]. V0, V1, and V2 are the indices of the vertices describing each triangle.

Returned Value

result — A 2D byte array containing the shaded image.

Keywords

Data — Indicates that the vertex coordinates are in data units, the default coordinate system.

Mesh — When present and nonzero, a wire-frame mesh is drawn over the polygons, and they are not shaded.

Normal — Indicates that coordinates are in normalized units, within the 3D (0,1) cube.

Poly_Shades — Similar to the Shades keyword, except one shade per polygon is passed to POLYFILL rather than one shade per vertex.

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

T3d — Enables the 3D to 2D transformation contained in the homogeneous 4-by-4 matrix !P.T. If this keyword is set, the system variable !P.T must contain a valid transformation matrix.

XSize — The number of columns in the output image array. If omitted, sets the number of columns equal to the x resolution of the currently selected display device.

YSize — The number of rows in the output image array. If omitted, sets the number of rows equal to the y resolution of the currently selected display device.

note	If you are using a PostScript or other high resolution graphics device, you should explicitly specify the XSize and YSize parameters. Making the output image of full device size (the default) will result in an insufficient memory error.

Discussion

Note that you must set up a 3D coordinate system prior to calling POLYSHADE.

POLYSHADE constructs the shaded surface using the scan line algorithm. The shading model is a combination of diffuse reflection and depth cueing. Polygons are shaded in one of two ways:

With constant shading, where each polygon is given a constant intensity.

With Gouraud shading, where the intensity is computed at each vertex and then interpolated over the polygon.

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

Example 1

Function POLYSHADE is often used in conjunction with procedure SHADE_VOLUME for volume visualization. This example creates a volume dataset and renders an isosurface from that dataset as shown in Isosurface of Volume Dataset.

; Create a 3D single-precision, floating-point array.

vol = FLTARR(20, 20, 20)

; Create the volume dataset.

FOR x=0L, 19 DO FOR y=0L, 19 DO FOR z=0L, 19 DO $

   vol(x, y, z) = SQRT((x-10)^2 + (y-10)^2 + $

   (z-10)^2) + 1.5 * COS(z)

LOADCT, 3

; Find the vertices and polygon at a contour level of 7.

SHADE_VOLUME, vol, 7, v, p

; Set up an appropriate 3D transformation.

SURFACE, FLTARR(2, 2), /Nodata, /Save, $

   XRange=[0, 20], YRange=[0, 20], $

   ZRange=[0, 20], XStyle=4, YStyle=4, ZStyle=4

; Render the image. Note that the T3d keyword has been set so that

; the 3D transformation established by SCALE3 is used.

image = POLYSHADE(v, p, /T3d)

; Display the image.

TV, image

Figure 13-14: Isosurface of Volume Dataset

Example 2

Building on Example 1, now use the Shades keyword to shade according to height instead of shading according to the light source.

See vtkPOLYSHADE for an example of colored shading according to the light source.

c = v(2,*)

c = INTERPOL( [64,192], [MIN(c,Max=m),m], c )

image = POLYSHADE( v, p, /T3d, Shades=c )

TV, image

Figure 13-15: Isosurface of Volume Dataset, with Shades keyword