WgSurfaceTool Procedure

Reference Guide > W Routines > WgSurfaceTool Procedure

Creates a surface window with a built-in set of controls: these controls allow you to interactively modify surface parameters and view the result of those modifications.

Usage

WgSurfaceTool, surface_data

Input Parameters

surface_data — A 2D variable containing surface data.

Keywords

Auto_congrid — If present and nonzero, the z variable is resized to 50-by-50 (with CONGRID) prior to drawing the surface. This enables PV‑WAVE to draw the surface much faster, although there is a chance that some surface detail is lost.

Auto_redraw — If present and nonzero, the surface is automatically redrawn any time one of the surface parameters is adjusted.

Cmap — The index of the color table to load when the widget is created; a positive integer in the range (0–18).

Elevation — If present and nonzero, the surface is drawn using simple elevation shading. Elevation and Gouraud are mutually exclusive.

Gouraud — If present and nonzero, the surface is drawn using Gouraud shading. Gouraud and Elevation are mutually exclusive.

Lines — If present and nonzero, lines are drawn instead of a grid.

Lower — If present and nonzero, only the lower portion of the grid is drawn. Lower and Upper are mutually exclusive keywords.

Nogrid — If present and nonzero, no grid is drawn on the surface.

Parent — The widget or shell ID of the parent widget (long). If parent is not specified, WgSurfaceTool runs on its own (i.e., in its own event loop).

Position — A two-element vector specifying the x- and y-coordinates of the upper-left corner of the SurfaceTool window (long integer). The elements of the vector are [x, y], where x (horizontal) and y (vertical) are specified in pixels. These coordinates are measured from the upper-left corner of the screen.

Skirt — If present and nonzero, a skirt is drawn connecting the surface to the x- and y-axes. Refer to Surface with and without a Skirt for an example of a surface with and without a skirt.

Shell — The ID of the newly created widget. If the procedure fails, zero (0) is returned.

Title — A string containing the title that appears in the header of the SurfaceTool window. Default value is “Surface Tool”.

Upper — If present and nonzero, only the upper portion of the grid is drawn. Upper and Lower are mutually exclusive keywords.

Xrot — The initial counter-clockwise rotation of the surface around the x-axis, measured in degrees.

Zrot — The initial counter-clockwise rotation of the surface around the z-axis, measured in degrees.

Color/Font Keywords

For additional information on the color and font keywords, see Setting Colors and Fonts in the PV‑WAVE Application Developer’s Guide.

Background — Specifies the background color name.

Basecolor — Specifies the base color.

Font — Specifies the name of the font used for text.

Foreground — Specifies the foreground color name.

Discussion

WgSurfaceTool, shown in WgSurfaceTool Window, is an interactive window that lets you use the mouse to control the orientation and appearance of a displayed surface.

Figure 19-11: WgSurfaceTool Window

Event Handling

You can use the SurfaceTool widget in one of the following two ways:

From the WAVE> prompt — Enter the procedure name at the WAVE> prompt to display the SurfaceTool widget. The SurfaceTool widget handles its own event loop by calling WwLoop.

Stand-alone widget in its own window created by another application — The SurfaceTool widget has its own Main window, but the application (not the SurfaceTool widget) handles the event loop by calling WwLoop.

The output parameter shell can be returned only if you also supply the input parameter parent.

Contents of the Window

The SurfaceTool window has three main parts — the display area, the control area, and the message area.

SurfaceTool Display Area

The display area is the largest area of the window; it is where the surface is displayed.

SurfaceTool Control Area

Use the following controls to operate the SurfaceTool window:

Surface (menu) — From the menu, choose the method by which the surface is drawn. The choices are: Fishnet (mesh), Lines (lines in one direction only), and None (no lines appear superimposed on a shaded surface).

Sides (menu) — From the menu, choose the representation of the top and bottom sides of the surface. The choices are: Both (lines on both top and bottom), Upper (lines on upper surface only), and Lower (lines on lower surface only).

Skirt — Controls whether a skirt is added to the surface. A skirt helps establish a frame of reference between the surface and the
x-, y-, and z-axes. Refer to Surface with and without a Skirt for an example of a surface with and without a skirt.

Shade (menu) — From the menu, select the algorithm by which the surface is shaded. The choices are: None (no shading), Gouraud, and Elevation.

X and Z Rotation — These controls allow you to rotate the surface (counter-clockwise around the x- or z-axis) a specified number of degrees. The current rotation is shown in the text field to the right of the slider. To modify the rotation, either enter a new value in one of the text fields, or use either slider. If you enter a new value into a text field, press <Return> to apply the new value to the slider and the surface. If you use the sliders, the change is applied immediately as the slider moves.

Auto Redraw — Controls whether the contents of the display area are redrawn every time a modification is made to one of the controls in the SurfaceTool control area.

Auto Congrid — The surface is resized to 50-by-50 (with CONGRID) prior to drawing the surface, for faster display of large datasets. The default is for Auto Congrid to be enabled. Auto Congrid does not affect the actual data; it only affects the display of the data.

Redraw — Causes the contents of the SurfaceTool display area to be redrawn.

Dismiss — Destroy the SurfaceTool window and erase it from the screen.

SurfaceTool Message Area

The message area displays the PV‑WAVE command that is being used to display the surface.

Figure 19-12: Surface with and without a Skirt

Example

Enter the commands shown below into a file, and compile the procedure with the .RUN command. If the variable parent is defined, WgSurfaceTool is created as a child of parent; otherwise, WgSurfaceTool runs on its own (i.e., in its own event loop).

When you are finished interacting with the WgSurfaceTool window, close it by clicking on the Dismiss button.

PRO Sample_wgsurfacetool, parent, tool_shell

   ; Create a "dummy" variable to view as view as a surface using

   ; WgSurfaceTool.

   x = DIST(75)

   IF N_ELEMENTS(parent) NE 0 THEN BEGIN

      ; Create WgSurfaceTool as a child of "parent". The window

      ; of the newly created widget is returned via the optional

      ; output parameter "tool_shell".

      WgSurfaceTool, x, Parent=parent, Shell=tool_shell

   ENDIF ELSE BEGIN

      ; Create WgSurfaceTool and display it as its own Main

      ; window. In other words, the WgSurfaceTool window runs on

      ; its own (i.e., in its own event loop).

      WgSurfaceTool, x

   ENDELSE

END