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.)

win_num—The number of the graphics window to use for the View Orientation window. Since this window is left on the screen when VIEWER returns, it is up to the calling program to delete it when desired. (The View Control window is automatically deleted when VIEWER returns.)

xsize, ysize—The X and Y dimensions, respectively, of the graphics window that VIEWER is setting up the view for.

size_fac—A factor controlling the size of the View Orientation window. The X dimension of the View Orientation window is (size_fac * xsize) and the Y dimension is (size_fac * ysize). Typically, size_fac should be in the range 0.5 to 1.0.

xpos, ypos—The location (x and y positions, respectively) for the View Orientation and View Control windows.

If the View Orientation window is near the bottom of the screen, then the View Control window is created above the View Orientation window. Otherwise, the View Control window is created below the View Orientation window.

colors—The value (number of colors to allocate) to use as the Colors keyword value in the WINDOW procedure call. A typical value for an 8-bit color system is 128 or 256.

retain—The value (flag) to use as the Retain keyword value in the WINDOW procedure call. Typically this is the value 1 or 2.

For more information on colors and retain, see the description of the WINDOW procedure in the PV‑WAVE Reference.

xdim, ydim, zdim—The size (first, second, and third dimension, respectively) of the array containing the data that is displayed using the view specified by VIEWER.

For example, if a 20-by-30-by-40 array is to be displayed using SHADE_VOLUME and POLYSHADE, then xdim should be 20, ydim should be 30, and zdim should be 40.

If a 20-by-30 array is to be displayed using the SURFACE or CONTOUR procedures, then xdim should be 20, ydim should be 30, and zdim should be (MAX(array)+1.0).

Ax—On input, if this keyword is omitted, or if the variable passed to Ax is undefined, then no controls for setting the view rotation about the x-axis are displayed.

If a valid value is passed to Ax, then this value is the initial (default) view rotation about the x-axis.

Ay—The view rotation about the y-axis (similar to Ax).

Az—The view rotation about the z-axis (similar to Ax).

On output, the Ax, Ay, Az input keywords each return a single floating-point value containing the x, y, and z rotation, respectively, that was selected.

The calling program does not need to do anything with the returned values Ax, Ay, and Az, since VIEWER automatically calls CENTER_VIEW to set the system view transformation !P.T, as well as !P.T3D, !X.S, !Y.S, and !Z.S. The calling program may, however, use these returned values in subsequent calls to VIEWER to let users “pick up where they left off.”

Bg_Color—The window background color. (Default: 0)

Bot_Color—The bottom shadow color for buttons. (Default: 0)

Cut_Plane—On input, if this keyword is omitted, or if the variable passed to Cut_Plane is undefined, then no controls for setting the slicing plane are displayed.

For the cut-away controls to be displayed, a previously-defined variable must be passed to Cut_Plane. If this variable is a valid (3, 2) integer array, then it is assumed to contain the initial (default) slicing plane.

If Cut_Plane is a valid array, then its contents are interpreted as shown in the following table:

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 the variable is a valid (6, n) integer array, then it is assumed to contain the initial (default) cutting volumes. This (6, n) array contains subscript ranges in the display array 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:

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:

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

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 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.

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 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:

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 View Control Window and Figure 18-9: View Orientation Window on page 1338.

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.

note

Use only the Ax, Az, and Zoom keywords when setting up a view for SURFACE or SHADE_SURF, since these 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.)

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.

If the Cut_Plane keyword is supplied to VIEWER, controls are provided for setting the slicing plane. The rotation and position of the slicing plane can be set. The center of the slicing plane can not be located outside the original volume. The slicing plane is visible in the View Orientation window.

If the Cut_Vol keyword is supplied to VIEWER, then controls are provided for setting the cut-away volume(s). The x size, y size, z size, x position, y position, and z position for each cut-away volume can be set. The size of the cut-away can not be larger than the original volume. No part of any cut-away volume may be positioned outside the original volume.

Three additional buttons, CLEAR, NEXT, and NEW, are also provided in the View Control window:

To create a new cut-away, click on the NEW button. This creates a small new cut-away near the coordinate origin. This cut-away is visible in the View Orientation window. You can then set the size and position of this cut-away by using the [+] and [–] buttons.

If multiple cut-aways have been defined, the NEXT button allows users to toggle between them to modify their size and position.

When you have finished setting the parameters, click the DONE button to set the view and return the parameters to the calling program.

If the Out_Mode keyword has been set, then clicking the DONE button does not cause a return to the calling program unless users have specified a view in which all the vertices of the view cube lie completely within the View Orientation window. In this case, users then need to change the view parameters (rotation, zoom, and/or perspective) before they could exit.

When VIEWER returns to the calling program, the View Control window is deleted, but the View Orientation window is left on the screen.

RESET can be used to reset all the parameters to their initial state.

For demonstrations of the VIEWER procedure, use the 4-D Data, Medical Imaging, Oil/Gas Exploration, and CFD/Aerospace buttons on the PV-WAVE Demonstration Gallery. To run the Gallery, enter wave_gallery at the WAVE> prompt.