VIEWER Procedure

Lets users interactively define a 3D view, a slicing plane, and multiple cut-away volumes for volume rendering. (Creates a View Control and a View Orientation window in which to make these definitions.)


`Cut_Plane(0, 0)`	The plane's angle of rotation about the x-axis.
`Cut_Plane(1, 0)`	The plane's angle of rotation about the y-axis.
`Cut_Plane(2, 0)`	Ignored.
`Cut_Plane(0, 1)`	The x-coordinate of the center of the plane.
`Cut_Plane(1, 1)`	The y-coordinate of the center of the plane.
`Cut_Plane(2, 1)`	The z-coordinate of the center of the plane.

NOTE: The slicing plane is rotated about the y-axis first, then about the x-axis. If the variable passed to Cut_Plane is defined but is not a valid (3, 2) array, then controls to set the slicing plane are displayed, the initial (default) slicing plane is defined with no rotation about the x- or y-axes, and the center point of the plane is at (xdim/2, ydim/2, zdim/2).

On output, the variable passed to Cut_Plane is always a valid (3, 2) single-precision floating-point array in the form previously described.

You can use the array returned from Cut_Plane as input to the SLICE_VOL procedure to extract the slice, or in subsequent calls to VIEWER.

Cut_Vol On input, if this keyword is omitted, or if the variable passed to Cut_Vol is undefined, then no controls for setting the cut-away volume(s) are displayed.

For the cut-away controls to be displayed, a previously-defined variable must be passed to Cut_Vol. If this variable is a valid (6, n) integer array, then it is assumed to contain the initial (default) cutting volumes. This (6, n) array contains the subscript ranges in the display array that are to be cut away.

For example, if a (6, 2) array called ca is passed in, then two initial cutting volumes are defined. In this case, the contents of ca are interpreted as follows:


`ca`(0, 0)	x dimension of the first cut-away.
ca(1, 0)	y dimension of the first cut-away.
ca(2, 0)	z dimension of the first cut-away.
ca(3, 0)	x position of the first cut-away.
ca(4, 0)	y position of the first cut-away.
ca(5, 0)	z position of the first cut-away.
ca(0:5, 1)	Defines second cut-away (similar to ca(0:5, 0)).

If the variable passed to Cut_Vol is defined, but is not a valid (6, n) array, then no initial cut-aways are defined, although the controls to define cut-aways are displayed.

On output, the variable passed to Cut_Vol is always a valid (6, n) integer array of the form previously described. If you do not define any cut-aways, then this variable is returned as a (6, 1) array containing all zeroes.

Typically, after the cut-away information is returned to the calling program, the array of data to be displayed is modified by the calling program using the cut-away information. This modification usually involves setting portions of the display array to zero before using the display array with other commands, such as RENDER, SHADE_VOLUME, VOL_REND, and VECTOR_FIELD3.

For example, if the display array is a 20-by-30-by-40 array (xdim=20, ydim=30, zdim=40) and the variable returned from Cut_Vol is a (6, 1) array containing the values:

[19, 10, 13, 0, 6, 24]

then the portions of the display array da to set to zero are as follows:

da(0:(0+19), 6:(6+10), 24:(24+13)) = 0

You may use the array returned from Cut_Vol in subsequent calls to VIEWER.

Fg_Color The foreground color. Used for buttons and for the current cut-away volume. The default is !P.Color.

HL_Color The color to use when highlighting buttons and for drawing the slicing plane. The default is !P.Color.

Out_Mode If present and nonzero, then users are not allowed to exit VIEWER until they have specified a view in which all the vertices of the view cube lie completely within the View Orientation window.

NOTE: Setting Out_Mode to 1 ensures that VIEWER always sets up a view that is compatible with POLYSHADE. (POLYSHADE will not work properly if one or more polygon vertices lie outside the window.)

Persp

On input, if this keyword is omitted, or if the variable passed to Persp is undefined, then no controls for setting the view perspective projection distance are displayed.

If a valid value is passed to Persp, then this value is used as the initial (default) setting for the perspective projection, and controls for setting the perspective are displayed.

On output, this input keyword returns the perspective projection distance that was selected.

The calling program does not need to do anything with the returned values for Zoom or Persp, since VIEWER automatically sets the view. However, you may use the returned value(s) in subsequent calls to VIEWER.

Top_Color The top shadow color for buttons. Also used to draw the view cube. The default is !P.Color.

Zoom On input, if this keyword is omitted, or if the variable passed to Zoom is not a valid scalar or three-element vector, then no controls for setting the Zoom factor(s) are displayed.

If the variable passed to Zoom is a single value, then this value is used as the initial (default) setting for the zoom factor and a single control is provided for zooming the view equally in all three dimensions (x, y, and z).

If the variable passed to Zoom is a three-element vector, then these three values are the initial (default) values for the zoom factors and three controls are provided for zooming the view independently in the x, y, and z directions.

On output, this input keyword returns the Zoom value(s) that was selected.

Discussion

VIEWER returns the view parameters, slicing plane parameters, and cut-away volume coordinates to the calling program.

VIEWER automatically defines the view by calling the procedure CENTER_VIEW, but it is up to the calling program to decide what to do with any slicing plane or cut-away information returned to it. It is also up to the calling program to perform the rendering.

NOTE: This procedure sets the system variables !P.T, !P.T3D, !X.S, !Y.S, and !Z.S, overriding any values you may have previously set. (These system variables are described in Chapter 4, System Variables.)

Due to the large amount of code in this procedure, the following command must be entered (once per PV-WAVE session) before any procedure that calls VIEWER can be run:

WAVE .size 32766 32766

Interactive Usage

When VIEWER is called, a View Control and a View Orientation window are created that let users interactively define 3D viewing parameters. These windows are shown in

Figure 2-141

Figure 2-143

Figure 2-141 The View Control window contains buttons used for setting the view, slicing plane, and cut-away volume parameters.

Figure 2-142 The View Control window contains buttons used for setting the view, slicing plane, and cut-away volume parameters.

The controls (buttons) provided for the user depend on the keywords supplied to VIEWER. For example, if you do not wish the user to be able to set the y rotation parameter, then do not use the Ay keyword.

TIP: It is advisable to use only the Ax, Az, and Zoom keywords when setting up a view for SURFACE or SHADE_SURF, since these procedures are limited in the type of viewing transformation they can utilize. (Other commands, such as PLOTS, POLYFILL, POLY_PLOT, and POLYSHADE, are compatible with most view transformations; therefore, you may freely use the Ay and Persp keywords when setting up the view for these routines.)

Figure 2-143 The View Orientation window displays a cube representing the current state of the parameters set in the View Control window.

Figure 2-144 The View Orientation window displays a cube representing the current state of the parameters set in the View Control window.

The available buttons in the View Control window are for X rotation, Y rotation, Z rotation, Perspective, and Zoom. Depending on how VIEWER is called, the Zoom keyword may consist of a single control, in which case the view is zoomed equally in the x, y, and z dimensions. There may also be three zoom controls provided, in which case the zoom factors for the x, y, and z dimensions may be set independently. There is also a NONE button provided for turning off the perspective projection.

NOTE: If the zoom factor is large, or the perspective parameter is small, then the cube display in the View Orientation window may be erroneous. To cure the problem, reduce the zoom or increase the perspective (or set the perspective to NONE).

All of the parameters can be changed by clicking on the plus [+] or minus [-] button for that parameter. The [+] button increases the value of that parameter and the [-] button decreases it. For rapid (coarse) control, use the left mouse button. For fine control, use the middle mouse button. For extra-fine control, use the right mouse button.