PV‑WAVE users can create high quality, interactive graphics through the use of the PV‑WAVE link to the Visualization Toolkit (VTK). The Visualization Toolkit is an Open Source toolkit for creating both simple and complex visualizations in 3D using OpenGL, a low-level software interface to graphics hardware, for high-performance, accelerated graphics. In addition to convenience routines that have been written to access some of the more common VTK utilities, all of the functionality available in the Visualization Toolkit is available to PV‑WAVE users. The two products complement each other well. PV‑WAVE excels at data access, data manipulation, numerical algorithms, data filtering, user interface development, and many interactive 2D graphical tasks. The Visualization Toolkit is a best-of-breed tool for creating complex 3D visualizations. Together they provide a simple and quick way to build tools for Visual Data Analysis.

The VTK toolkit was integrated into PV‑WAVE using a Tcl shell as an intermediary. Tcl is a popular scripting language, see www.tcl.tk for more information. The VTK toolkit already has a binding for the Tcl language. PV‑WAVE spawns a Tcl shell and communicates with it using sockets, sending VTK commands formatted for Tcl.

Figure 7-1: Creating the Tcl Shell shows how the two routines vtkINIT and vtkCOMMAND are used to create the Tcl shell and send commands to it, including VTK commands:

The vtkCOMMAND procedure is used in PV‑WAVE to send individual commands to the shell, and higher level wrappers have been built around this to allow many common PV‑WAVE plotting commands to be accessed in a manner similar to existing PV‑WAVE commands. Some of these commands include vtkWINDOW, vtkLIGHT, vtkPLOTS, vtkSURFACE, and vtkPOLYSHADE. The full power of the VTK visualization pipeline can still be accessed but requires specific knowledge of the VTK objects and methods.

A set of commands for packaging data into one of five supported data types in VTK is also provided, allowing data to be easily sent from PV‑WAVE to VTK.

Many procedures have a Name keyword which allows you to either choose a name for the object you are creating or return a generated one. This acts as a bridge between the high-level PV‑WAVE wrappers and low-level VTK functionality. Thus you can create a vtkSURFACE object and later use low-level VTK commands to change specific properties of this object.

Currently the VTK windows cannot be integrated into a user interface created with PV‑WAVE widgets. However, widgets can be used to size, position and annotate an object in a VTK window by passing keywords from the widget to the vtkWINDOW.

You can run the demonstration programs and look at the code in:

Where <RW_DIR> is the main Rogue Wave directory.

These routines can be modified to work with your own data.

You can download the Visualization Toolkit and reference documentation frompublic.kitware.com.

PV‑WAVE users can now use the improved 3D visualization capabilities and rendering engine in VTK 7.1.0 through the VTK7 OPI routines. The VTK7 toolkit is integrated into PV-WAVE using a Tcl shell as an intermediary, identical to the original VTK toolkit. The toolkit has a binding for the Tcl language and makes use of the Tcl “wrapper language” to access the VTK APIs. PV-WAVE employs a similar technique using the PV-WAVE language as the “wrapper language” for access to many common PV-WAVE commands. VTK7 can be implemented using PV-WAVE’s higher-level wrapper functions by substituting the VTK7 OPI routines for the VTK OPI routines (i.e., vtk7INIT replaces vtkINIT). This functionality is available for the following PV-WAVE procedures or functions:

The VTK7 OPI spawns a Tcl shell and communicates using sockets like the original VTK OPI, sending VTK commands formatted for Tcl. The two low-level routines vtk7INIT and vtk7COMMAND are used to create the Tcl shell and send commands to it, including non-PV-WAVE VTK commands. The vtk7COMMAND procedure is used in PV‑WAVE to send individual commands to the Tcl shell using the Tcl “wrapper language.”

If you use the vtk7COMMAND to send commands to the Tcl shell, you may need to update your code for backwards-incompatible changes in the Visualization Toolkit, specifically around the pipeline objects.

Some of the more important changes are:

For a more complete list of the changes that may affect you, see www.vtk.org/Wiki/VTK/VTK_6_Migration/Overview for more information regarding the VTK pipeline re-architecture.

The routine vtkINIT is used to spawn a Tcl process through which VTK commands may be sent. The spawned process will continue executing until vtkCLOSE is called. Repeatedly calling vtkINIT will not cause multiple Tcl processes to be created; only one will be allowed to run at any given time for a PV‑WAVE session. You can use the /Print parameter to vtkINIT to cause debug information from the Tcl process to be logged in the PV‑WAVE console. Most VTK wrapper routines, with the exception of vtkCOMMAND and the dataset creation routines, will automatically call vtkINIT for you if you have not done so manually.

To create a VTK window in which 3D OpenGL graphics can be rendered, use the vtkWINDOW command. It is used in a manner similar to the WINDOW command for PV‑WAVE windows. You can specify a window index to be used to refer to this window, or use /Free to allow an unused index to be chosen for you. There are two important keywords for vtkWINDOW that affect how 3D objects are displayed in it: /NoRender and /NoInteract.

Normally VTK windows operate much like PV‑WAVE windows, in that as you issue commands to add plots, annotation, axes and other objects to the window, the results are immediately rendered and displayed. For performance reasons you do not always want to do this for VTK windows, and would rather add all of the objects to be rendered before actually rendering and displaying the scene. If you specify /NoRender in a call to vtkWINDOW, then you are turning off automatic rendering until you explicitly call the vtkRENDERWINDOW routine. Use of the /NoRender routine does not affect calls to the low-level vtkCOMMAND routine.

By default VTK windows have a set of mouse interactions built into them. This allows you to rotate, zoom, and pan your view interactively. If you do not want these default interactions then specify /NoInteract with vtkWINDOW and any changes in camera view will be under programmatic control only. The default mouse interaction for VTK windows including the following features:

The following routines operate exactly like their PV‑WAVE counterparts to manage windows:

In order to save the contents of VTK windows, you can use the procedure vtkPPMWRITE. This causes the current contents of the selected or current VTK window to be saved to a file in PPM (Portable PixMap) format. This is the only format supported by VTK for saving the contents of VTK windows. The corresponding function vtkPPMREAD can be used to read a PPM file and return a 24 bit image that can be displayed in PV‑WAVE. The routine vtkTVRD functions much as the PV‑WAVE TVRD routine but is a wrapper to calls to vtkPPMWRITE and vtkPPMREAD.

The following routines are PV‑WAVE wrappers which mimic the functionality of common PV‑WAVE graphics routines. The source code for these routines are available as PV‑WAVE procedures and act as good examples of using the low-level VTK functionality.

In the PV‑WAVE wrappers for VTK there are a number of ways to specify colors. The VTK windows always display in 24-bit color, although we can use the PV‑WAVE color table values as we will see. For parameters that expect as input a single color value, the color can be specified in any one of the following ways (in this case for the color red):

For parameters that expect as input a 1D or 2D array of color values, such as the Shades keyword for vtkSURFACE or Color keyword for vtkPOLYSHADE, the color can be specified as arrays of the above. For example for vtkSURFACE we could pass a 2D array of short integers to make use of the PV‑WAVE color table, or a (3, m, n) array of float values between 0.0 and 1.0.

For many users, the above high-level VTK wrapper routines will provide sufficient functionality for creating 3D charts similar to what is already available in PV‑WAVE, but now using accelerated OpenGL graphics. Others may want to make use of the vast amount of functionality available in VTK including source code developed by other VTK users. All of this is possible using the low-level interface provided to VTK through PV‑WAVE. If you intend to use the low-level functionality available in VTK you will need to obtain documentation on VTK. See the references in Demonstration Programs for more details.

Most low-level VTK functionality is accessed using vtkCOMMAND, which simply sends a text string containing any valid Tcl or VTK wrapper command to the spawned Tcl process. You can send individual commands or even invoke pre-written Tcl scripts through the “include” Tcl command.

Creation and access to VTK objects via Tcl (and thus vtkCOMMAND from PV‑WAVE) is made using this convention:

To create a VTK object in Tcl:

Vtk_class_name my_vtk_variable name

To call a method of a VTK object in Tcl:

My_vtk_variable_name method_name param_1 param_2 param_n

For example to create a VTK light source and set the color to red you could use these commands from PV‑WAVE:

vtkCOMMAND, ‘vtkLight my_light’

vtkCOMMAND, ‘my_light SetColor 1.0 0.0 0.0’

The use of the Tcl wrappers for VTK commands are documented in the references mentioned in Demonstration Programs and in reference pages available with the VTK download. If you download the VTK distribution from http://public.kitware.com, there are hundreds of example Tcl scripts for creating different kinds of VTK visualizations. These scripts can be used in developing PV‑WAVE wrappers to create these same visualizations from PV‑WAVE.

VTK supports five basic dataset representations. These represent the different ways in which data can be organized for use in visualizations. This includes representations from simple points in 3D space, polygons, grids, and voxels (volume elements). The following PV‑WAVE wrappers offer a way to create, store, and pass these datasets to VTK:

With all of the above dataset types, the most fundamental element is a point. In VTK there are attributes that can be associated with points and used in various ways for visualizations, such as for coloring points or drawing vectors associated with points. Creating these attributes is accomplished using the PV‑WAVE procedure vtkADDATTRIBUTE. Attributes created with this routine can be used in calls to the above five dataset creation routines. See the references in Demonstration Programs for more details.

Here are some examples of using the PV‑WAVE VTK Integration routines that show how VTK can be accessed in a manner very similar to existing PV‑WAVE graphic routines.

Use the following command to create a surface plot:

vtkSURFACE, DIST(10), Shades=’slate_blue’

This one command automatically invokes vtkINIT and vtkWINDOW to open a window. Since only one color was specified (in this case using a named color), the entire surface is shaded using that color.

This example shows how we can use a vertex/polygon list to create a plot in much the same way as with POLYSHADE. Since the colors we specify are short integers, the colors used are from the current PV‑WAVE color table, which was loaded using TEK_COLOR in this case.

vertex_list = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], $
[1.0, 1.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0], $
[1.0, 0.0, 1.0], [1.0, 1.0, 1.0], [0.0, 1.0, 1.0]]

polygon_list = [4, 0, 1, 2, 3, 4, 4, 5, 6, 7, $
4, 0, 1, 5, 4, 4, 2, 3, 7, 6, 4, 0, 4, 7, 3, 4, 1, 2, 6, 5]

TEK_COLOR

vertex_colors = [2,3,4,5,6,7,8,9]

vtkPOLYSHADE, vertex_list, polygon_list, Color=vertex_colors

vtkWINDOW, /Free, Background='000077'XL, /NoRender

vtkSURFACE, HANNING(20,20)*20.0, Shades=[1.0, 0.0, 0.0, 0.5]

vtkTEXT, 'Transparent Surface', Position=[10, 10, 20], $
/Follow, Color='green'

vtkRENDERWINDOW

In this example we explicitly call vtkINIT so that we can turn on logging of all Tcl commands. We also manage the window creation and deletion and rendering ourselves.

vtkINIT, /Print

vtkWINDOW, /NoRender

vtkSCATTER, RANDOMN(seed, 3, 100), Color='blue'

vtkRENDERWINDOW

HAK, /Mesg

vtkWDELETE

vtkCLOSE

More examples are provided with the PV‑WAVE distribution.

For additional examples see the procedures in the directory <RW_DIR>/vtk-3_2/demo or <RW_DIR>/vtk7-1_0/demo (where <RW_DIR> is the path to the PV-WAVE installation).