Visualizing with VTK A Tutorial

In this tutorial we introduce basic conceptsbehind the Visualization Toolkit (VTK). An overview of the system, plus some detailed examples, will assist you in learning this system. The tutorial tar- gets researchers of any discipline who have 2D or 3D data and want more control over the visualization process than a turn-key system can provide. It also assists developers who would like to incorporate VTK into an application as a visualization or data process- ing engine. Although this tutorial can only provide an introduction to this extensive toolkit, we’ve provided references to additional material. What is VTK? VTK1 is an open-source (see the sidebar “Open Source Breakout”), portable (WinTel/Unix), object-ori- ented software system for 3D computer graphics, visu- alization, and image processing. Implemented in C++, VTK also supports Tcl, Python, and Java language bind- ings, permitting complex applications, rapid applica- tion prototyping, and simple scripts. Although VTK doesn’t provide any user interface components, it can be integrated with existing widget sets such as Tk or X/Motif. VTK provides a variety of data representations includ- ing unorganized point sets, polygonal data, images, vol- umes, and structured, rectilinear, and unstructured grids. VTK comes with readers/importers and writ- ers/exporters to exchange data with other applications. Hundreds of data processing filters are available to oper- ate on these data, ranging from image convolution to Delaunay triangulation. VTK’s rendering model sup- ports 2D, polygonal, volumetric, and texture-based approaches that can be used in any combination. VTK is one of several visualization systems available today. AVS2 was one of the first commercial systems available. IBM’s Data Explorer (DX),3 originally a com- mercial product, is now open source and known as OpenDX. NAG Explorer4 and Template Graphics Amira (see http://www.tgs.com/Amira/index.html) are other well-known commercial systems. VTK is a general-purpose system used in a variety of applications, as seen in Figure 1. Because VTK is open source, faculty at many universities—including Rens- selaer Polytechnic Institute, State University of New York at Stony Brook, the Ohio State University, Stanford, and Brigham and Women’s Hospital use VTK to teach cours- es and as a research tool. National labs such as Los Alam- os are adapting VTK to large-scale parallel processing. Commercial firms are building proprietary applications on top of the open-source foundation, including med- ical visualization, volume visualization, oil exploration, acoustics, fluid mechanics, finite element analysis, and surface reconstruction from laser-digitized, unorga- nized point-clouds. VTK began in December 1993 as companion software to the text The Visualization Toolkit: An Object-Oriented Approach to 3D Graphics by Will Schroeder, Ken Martin, and Bill Lorensen (Prentice Hall). In 1998 the second edition of the text appeared, with additional authors Lisa Avila, Rick Avila, and Charles Law. Since that time a sizable community has grown up around the software, including dozens of others as developers, often submit- ting bug fixes or full-blown class implementations. These community efforts have helped the software evolve. For example, David Gobbi in the Imaging Research Laboratories at the John P. Robarts Research Institute, University of Western Ontario, has reworked VTK’s transformation classes and is now an active developer. Architecture VTK consists of two major pieces: a compiled core (implemented in C++) and an automatically generated interpreted layer. The interpreted layer currently sup- ports Tcl, Java, and Python. C++ core Data structures, algorithms, and time-critical system functions are implemented in the C++ core. Common design patterns such as object factories and virtual func- tions insure portability and extensibility. Since VTK is independent of any graphical user interface (GUI), it doesn’t depend on the windowing system. Hooks into the window ID and event loop let developers plug VTK into their own applications. An abstract graphics model (described in the next section) achieves graphics portability. 0272-1716/00/$10.00 © 2000 IEEE Tutorial 20 September/October 2000 William J. Schroeder, Lisa S. Avila, and William Hoffman Kitware Visualizing with VTK: A Tutorial Interpreted layer While the compiled core provides speed and efficien- cy, the interpreted layer offers flexibility and extensi- bility. For example, using GUI prototyping tools such as Tcl/Tk, Python/Tk, or Java AWT permits building pro- fessional applications rapidly. These popular program- ming languages come with other packages such as Python’s numerical library NumPy. We used Tcl in the examples in this article. You can type in the example code included here and immediately see the results. Follow the instructions found at http://www. visualizationtoolkit.org/CGA/Instructions.htm to install VTK and start a Tcl shell with VTK support. The graphics model VTK has two major subsystems—the graphics model and visualization pipeline. The graphics model forms an abstract layer above the graphics language (for example, OpenGL) to insure cross-platform portability. When the development of VTK began in 1993, each computer plat- form had its own graphics language—XGL for Sun, Star- base for Hewlett-Packard, and gl for Silicon Graphics. Abstracting graphics concepts into a platform and device- independent layer created the graphics model. Since that time the industry has standardized on OpenGL. Although this is now the only low-level graphics language sup- ported in VTK, the abstract layer has not been abandoned. In the future, new graphics languages are likely to become popular and even replace OpenGL as a standard. Keep- ing this abstract layer lets us update VTK with new tech- nology without affecting backwards compatibility. We adapted the names of the classes in the graphics model from the movie-making industry. Lights, cam- eras, actors, and props are classes that the user instan- tiates to create a scene. You’ll find that the model used for 3D polygonal rendering (lights, cameras, actors) is analogous to the model used for volume and other types of rendering (lights, cameras, volumes). In the follow- ing sections we’ll walk through a simple example demonstrating these classes for surface polygonal and volume rendering. You may wish to type these com- mands into a properly installed Tcl interpreter as described in the previous section. Figure 2 shows the resulting image from this example. IEEE Computer Graphics and Applications 21 Open Source Breakout A model of software development called open source is gaining acceptance in the software world. Although the exact definition of open source remains debatable, the basic premise is that the source code is freely available to anyone who wants it. This differs greatly from commercial software, freeware, and shareware, all of which are normally distributed in a binary format only. The availability of source code to a wide audience creates many opportunities and advantages in the software development process. Recently, several high-profile projects have brought this model to the attention of the media and general public. Those projects include the Linux operating system, the Apache Web server (running 50 percent of the World Wide Web), and sendmail (the backbone for much of the e-mail sent today). Although people have shared source code since the beginning of computers, new business models, software development tools, and the Internet have allowed the practice to expand greatly in the past five years. Open-source software has many benefits. Eric Raymond in The Cathedral and the Bazaar: Musings on Linux and Open Source by an Accidental Revolutionary (O’Reilly Publishers) argues that open- source software development (the bazaar model) is inherently more scalable than closed-team development (the cathedral model). With more eyes looking at source code, bugs can be discovered and fixed faster. In addition, new developers join the development team at no extra cost. This has created more reliable and portable software with faster development cycles than many closed commercial offerings. With many developers in diverse geographical areas, testing becomes even more important. In the past 10 years business models have emerged to support open-source development. It may seem impossible for a company to survive by giving away software. However, companies can thrive around an open-source project. Some common ways of generating revenue include consulting, training, adding features, selling technical support, building proprietary end-user applications on top of open-source libraries, and selling development tools. 1 VTK can be used in diverse areas including medical visualization (left) and industrial inspection applica- tions (right). 2 Two renderers in a rendering window combine surface, volume, and 2D rendering. The left renderer contains a simple cube; the right renderer contains a polygonal isosurface and volume rendering of electron potential. The scalar bar indicates data range and its relationship to color. Render window and renderers To visualize your data, you first need to open a win- dow on the computer screen. vtkRenderWindow is an abstract superclass representing the object into which one or more renderers draw. Like most graphics objects, it automatically instantiates the correct device-depen- dent subclass for your platform. The vtkRenderWindow is a container class for vtkRenderer objects, and multi- ple renderers can be tiled within a single render win- dow to create complex visualizations. In this example we’ll place two renderers with different background col- ors side by side within the render window. The place- ment location is specified using normalized (0, 1) viewport coordinates in the render window: vtkRenderWindow renWin renWin SetSize 600 300 vtkRenderer ren1 ren1 SetViewport 0.0 0.0 0.5 1.0 ren1 SetBackground 0.8 0.4 0.2 renWin AddRenderer ren1 vtkRenderer ren2 ren2 SetViewport 0.5 0.0 1.0 1.0 ren2 SetBackground 0.1 0.2 0.4 renWin AddRenderer ren2 renWin Render The vtkRenderWindow object manages the render process, so a single Render() call will cause the window to map onto the screen and the renderers to update their display. At this point in the example only solid back- ground color will appear because we haven’t defined any props. Props, mappers, and properties Props are the objects added to the renderer to create a scene. The class vtkProp is an abstract superclass for all 2D and 3D props and contains information about visi- bility, orientation, size, and position. Props associate with a mapper and a property object. The mapper refers to an input data object (described in the section on the visualization pipeline), and it knows how to render the data object. The property object contains rendering parameters such as color and material properties. In the next three sections we’ll cover some concrete subclass- es for props, mappers, and properties that can be used for rendering 3D surface geometric data, 3D volumet- ric data, and 2D geometry, text, and images. Rendering 3D geometric data One specific subclass of vtkProp that can be used to represent 3D geometric data in a scene is vtkActor. The actor object will automatically create a default vtkProp- erty object, but requires the user to specify a subclass of vtkMapper. Depending on the nature of the geometry referred to by the mapper, either the subclasses vtk- DataSetMapper or vtkPolyDataMapper must be used. If the data contains points, lines, and polygons represent- ed using a vtkPolyData, then a vtkPolyDataMapper can be used. Otherwise, vtkDataSetMapper must be used. The following fragment of Tcl code can be used to cre- ate a polygonal cube and place it in the scene. In this code segment and others following, note that lines of code ending with a backslash (\) indicate a carryover of code that didn’t fit onto one line. The indented line following belongs with the preceding line. Simply delete the \ and type in a single line of code. vtkCubeSource cubeData vtkPolyDataMapper cubeMapper cubeMapper SetInput \ [cubeData GetOutput] vtkActor cubeActor cubeActor SetMapper cubeMapper ren1 AddProp cubeActor ren1 ResetCamera renWin Render Since the output of the vtkCubeSource object is polyg- onal data, an instance of vtkPolyDataMapper renders the data. The ResetCamera() method centers the cam- era on the data. The following fragment of Tcl code rotates the cube and changes the color to pink: cubeActor RotateX 30.0 cubeActor RotateY 20.0 [cubeActor GetProperty] \ SetColor 1.0 0.7 0.7 renWin Render Use the GetProperty() method of the actor to access the automatically created property object. Rendering 3D volumetric data The vtkImageData object can be used to represent one-, two-, and three-dimensional image data. As a sub- class of vtkDataSet, vtkImageData can be represented by a vtkActor and rendered with a vtkDataSetMapper. In 3D this data can be considered a volume. Alternatively, it can be represented by a vtkVolume and rendered with a subclass of vtkVolumeMapper. Since some subclasses of vtkVolumeMapper use geometric techniques to ren- der the volume data, the distinction between volumes and actors mostly arises from the different terminology and parameters used in volumetric rendering as opposed to the underlying rendering method. VTK currently supports three types of volume ren- dering—ray tracing, 2D texture mapping, and a method that uses the VolumePro graphics board.5 Although the example in this section uses the 2D texture mapping approach, you could change it to use an alternative method with only minor modifications. To begin our volume-rendering example, we’ll load a 3D structured data set of unsigned char values and use this as input for the volume mapper vtkVolumeTex- tureMapper2D. Tutorial 22 September/October 2000 vtkSLCReader negReader negReader SetFileName “neghip.slc” vtkVolumeTextureMapper2D negMapper negMapper SetInput \ [negReader GetOutput] The hardest step in volume visualization is often defining the transfer functions that map the scalar data values into color and opacity. In this example we’ll use a simple ramp from 0.0 to 0.2 for opacity, with the color function ranging through red, blue, and green. vtkPiecewiseFunction negOpacity negOpacity AddPoint 0 0.0 negOpacity AddPoint 255 0.2 vtkColorTransferFunction negColor negColor AddRGBPoint 64 1.0 0.0 0.0 negColor AddRGBPoint 128 0.0 0.0 1.0 negColor AddRGBPoint 196 0.0 1.0 0.0 The first value defined when adding a point into a transfer function is always the scalar value, with one value following it for a vtkPiecewiseFunction or an RGB triple following it for a vtkColorTransferFunction. Since we’re visualizing 8-bit data, the scalar values in this example range from 0 to 255. Now that we’ve defined the two required transfer functions, we can create the volume property and the volume. vtkVolumeProperty negProperty negProperty SetColor negColor negProperty SetScalarOpacity \ negOpacity vtkVolume negVolume negVolume SetMapper negMapper negVolume SetProperty negProperty ren2 AddProp negVolume ren2 ResetCamera renWin Render Intermixing geometry and volumes The VTK rendering process can combine multiple actors and volumes in the same scene. In the following example, a polygonal surface is displayed intermixed with the volume. vtkPolyDataReader posReader posReader SetFileName \ “poshipsurface.vtk” vtkPolyDataMapper posMapper posMapper SetInput \ [posReader GetOutput] vtkActor posActor posActor SetMapper posMapper ren2 AddProp posActor renWin Render The combined VTK rendering process has a few lim- itations. VTK doesn’t support translucency of geomet- ric data because the primitives aren’t sorted into a back-to-front ordering before rendering. Multiple vol- umes can be rendered in the same scene only if the bounds of the volumes don’t overlap. Opaque geometry can overlap volumes using the ray casting and texture mapping approaches, but not if a vtkVolumeProMapper is used because of limitations with this hardware. Rendering 2D data In addition to 3D geometric and volumetric data, VTK visualizes 2D data such as geometry, images, and text. In the examples given here we’ll render 2D data into a 3D renderer to intermix 2D and 3D data. Alternatively, if we only have 2D data, we can use an image viewer for visualization. The concept of actors, mappers, and properties applies to both 2D and 3D data, although some of the specific parameters change. In the code fragment below, we add annotation to the renderer that displays the cube. A vtkActor2D represents the title in the scene, a vtkTextMapper holds and renders the data (which in this case is a string), and the vtkActor2D automatically creates a vtkProperty2D. Note, here and in code seg- ments following, some long individual code words include hyphens because they didn’t fit onto one line. A hyphen, like a \, also indicates a carryover, but of a sin- gle word. When typing in the code, delete the hyphens to recreate a single word. vtkTextMapper titleMapper titleMapper SetInput \ “This is a Pink Cube” titleMapper \ SetJustificationToCentered vtkActor2D titleActor titleActor SetMapper titleMapper [titleActor GetProperty] \ SetColor 1 1 0 set pc [titleActor \ GetPositionCoordinate] $pc SetCoordinateSystemToNormalized- Viewport $pc SetValue 0.5 0.92 ren1 AddProp titleActor renWin Render The code required to change the color of the text resembles the code used to change the cube’s color. However, 3D actors are positioned using world coordi- nates, whereas we chose to position this 2D actor in a normalized viewport coordinate system. Since 2D data is often used for annotation, VTK offers several objects that combine multiple 2D actors and mappers into one 2D actor. For example, the vtkScalar- BarActor object combines text and 2D polygons to IEEE Computer Graphics and Applications 23 display a representation of a color lookup table. vtkScalarBarActor scalarBar scalarBar SetLookupTable negColor scalarBar SetTitle “Density” set sPC \ [scalarBar GetPositionCoordinate] $sPC SetCoordinateSystemTo- NormalizedViewport $sPC SetValue 0.8 0.1 ren2 AddProp scalarBar renWin Render If you’d like to write your own composite actor in C++, start with vtkScalarBarActor. This object creates the scalar bar representation using other VTK classes and uses the rendering functionality of these created map- pers to display the annotation object. Lights, cameras, and interaction Many VTK applications never explicitly create a vtk- Light or a vtkCamera, since the renderer will automat- ically create them if they’re not defined at the first render. Once the system creates a camera, you can access it from the renderer to change camera parameters such as position, focal point, and field of view. The cam- era contains some convenience methods for rotation about the position and the focal point such as Azimuth(), Elevation(), Roll(), Pitch(), and Yaw() (the angles are measured in degrees). set cam [ren2 GetActiveCamera] $cam Azimuth 20.0 $cam Elevation 10.0 renWin Render The light automatically created is a white light with the same position and focal point as the camera. If you use an interactor (as described later in this section), this light will follow the camera. You can use the following fragment of code to add a second light to the volume rendered scene. This light comes from the right side and is green. Since illumination is off by default in a volume property (ambient = 1.0, diffuse/specular = 0.0), the green light doesn’t alter the volume. vtkLight light light SetFocalPoint 0.0 0.0 0.0 light SetPosition 1.0 0.0 0.0 light SetColor 0.0 1.0 0.0 light SetIntensity 0.5 ren2 AddLight light renWin Render Clearly, we’d prefer to use mouse events