Table of Contents

Introduction
A brief introduction, with links to help you get vtk running on your display.
Getting started
A few basic hints that will help you get started.
Graphics Model
How to transform graphical data into pictures.
Visualization Pipeline
How to transform information into graphical data.
Scalar Visualization Algorithms
Color Mapping
Contouring/Isosurface.
Vector Visualization Algorithms
Hedgehogs
Oriented Glyphs
Stream Lines
Modeling Visualization Algorithms
Cutting/Slicing
Clipping
Additional Help
References

Introduction

The Visualization ToolKit (VTK) is an open source, freely available software system for 3D computer graphics, image processing, and visualization. VTK consists of a C++ class library, and several interpreted interface layers including Tcl/Tk, Java, and Python. VTK supports a wide variety of visualization algorithms including scalar, vector, tensor, texture, and volumetric methods; and advanced modeling techniques such as implicit modeling, polygon reduction, mesh smoothing, cutting, contouring, and Delaunay triangulation. In addition, dozens of imaging algorithms have been directly integrated to allow the user to mix 2D imaging / 3D graphics algorithms and data.

As Tcl is one of the easiest languages with which to learn VTK, this tutorial is organized as a set of Tcl code examples with explanations. It is assumed that the student is familiar with basic Unix commands, the Tcl interpreter, and the use of an editor. The examples we will be using were originally developed for the 2008 Workshop on Scientific Visualization and are based upon the example programs and data from Kitware. The workshop examples are available for download here: Tar file of the VTK workshop examples. See VTK Examples web page for more information.


Getting started

This tutorial assumes that you have downloaded and untared the workshop examples file. You should now have a materials directory with both a Data and a Demos subdirectory. You can cd into any of the subdirectories of the materials/Demos directory and run the VTK example by typing vtk followed by the example’s file name. For example:

scc1% cd materials/Demos/Simple/
scc1% vtk cone2.tcl

The most effective way for you to go through this tutorial is by running and modifying the appropriate workshop examples as we discuss them. Note: in many of the example files, some code lines are commented out. These lines represent alternative options for a particular function in the code. You should experiment with the code by changing which option is executed (i.e. comment out the original line and uncomment one of the alternatives) and watching the effect this has. It can also be helpful for you to browse the VTK documentation for the specific classes we discuss (links are provided). For documentation on all of the VTK classes you can go to the VTK Class Index.

Boston University SCV users, please go to the SCV VTK Help Page for information specific to the installation at this site. This will tell you on what machines VTK is available, how to set up your environment, how to set your display, and where the documentation is.


Graphics Model

VTK has an abstract graphics layer above the local host’s graphic software interface (usually OpenGL). This insures cross-platform portability and creates a device independent graphics layer. In the graphics model class names were adapted from the movie-making industry. Lights, cameras, actors, and props are all used to create a scene.

Render Window

In order to visualize your data, you will need to open a window and create a renderer. vtkRenderWindow is the class you will use to create a window and vtkRenderer is the class you will use to create the renderer which will draw in the window. The vtkRenderWindow is a container class for vtkRenderer objects. Within a VTK application you can have multiple windows and multiple renderers tiled within each window. Here is example Tcl code to create a simple window and renderer:

package require vtk

vtkRenderWindow renWin
   renWin SetSize 500 500

vtkRenderer ren1
   ren1 SetBackground 0.0 0.0 0.0

renWin AddRenderer ren1
renWin Render

This code is in the file materials/Demos/Simple/simple.tcl. To run:

scc1% cd materials/Demos/Simple/
scc1% vtk simple.tcl

Mappers, Properties, and Actors

Now that we know how to create a window, we can create an actor for our scene. vtkActor is the class you will use to represent 3D geometric data in the scene. To start we will need some data. We will use an instance of vtkConeSource to generate polygonal data for a cone. We will then use an instance of vtkPolyDataMapper to take the polygonal data from the vtkConeSource and create a rendering for the renderer. Here is example Tcl code to create a simple cone and a window and renderer:

package require vtk

vtkConeSource cone
   cone SetResolution 100

vtkPolyDataMapper coneMapper
   coneMapper SetInput [cone GetOutput]

vtkActor coneActor
   coneActor SetMapper coneMapper
   [coneActor GetProperty] SetColor 1.0 0.0 0.0

vtkRenderWindow renWin
   renWin SetSize 500 500

vtkRenderer ren1
   ren1 SetBackground 0.0 0.0 0.0

ren1 AddActor coneActor
renWin AddRenderer ren1
renWin Render

This code is in the file materials/Demos/Simple/cone.tcl. To run:

scc1% cd materials/Demos/Simple/
scc1% vtk cone.tcl

Interaction

In order to interact with the scene using the mouse we will use an instance of vtkRenderWindowInteractor. The interactor can be placed into joystick or trackball mode using the “j” or “t” keys. The left mouse button controls rotation, the middle mouse button controls panning, and the right mouse button controls zooming. The “r” key can be used to reset the camera. The “q” key is used to quit. Here is code to create a cone within an interactive window and renderer:

package require vtk
package require vtkinteraction

vtkConeSource cone
   cone SetResolution 100

vtkPolyDataMapper coneMapper
   coneMapper SetInput [cone GetOutput]

vtkActor coneActor
   coneActor SetMapper coneMapper
   [coneActor GetProperty] SetColor 1.0 0.0 0.0

vtkRenderWindowInteractor iren

vtkRenderWindow renWin
   renWin SetSize 500 500

vtkRenderer ren1
   ren1 SetBackground 0.0 0.0 0.0

ren1 AddActor coneActor
renWin AddRenderer ren1
iren SetRenderWindow renWin
iren Initialize

This code is in the file materials/Demos/Simple/cone2tcl. To run:

scc1% cd materials/Demos/Simple/
scc1% vtk cone2.tcl

Visualization Pipeline

The visualization pipeline is responsible for constructing the geometric representation that is then rendered by the graphics pipeline. In other words the visualization pipeline transforms informational data into graphical data which is then transformed into images by the graphics pipeline. VTK uses a data flow approach to transform informational data into graphical data. There are two basic types of objects involved:

  • vtkDataObject
  • represents data of various types: Image data, Rectilinear Grid, Structured Grid, Unstructured Points, Polygonal Data, Unstructured Grid
  • consists of geometry (point coordinates), topology (points or cells), and data attributes (Scalars, Vectors, Normals, Texture Coordinates, Tensors)
  • provides access to data
  • vtkProcessObject
  • filters which operate on data objects to produce new data objects
  • represent visualization algorithms

Data Objects and Process Objects are connected together to form a visualization pipeline.

Source -> Reader -> Filter -> Mapper -> Actor

Data Objects

VTK data objects have both topological and geometrical structure and can represent several types of data:

  • (a) Image/Volume Data (vtkImageData) datatypes
  • regular in both topology and geometry
  • examples: lines, pixels, voxels
  • applications: imaging CT, MRI
  • (b) Rectilinear Grid (vtkRectilinearGrid)
  • regular topology but geometry only partially regular
  • examples: pixels, voxels
  • (c) Structured Grid (vtkStructuredGrid)
  • regular topology and irregular geometry
  • examples: quadrilaterals, hexahedron
  • applications: fluid flow, heat transfer
  • (d) Unstructured Points (vtkPolyData)
  • no topology and irregular geometry
  • examples: vertex, polyvertex
  • applications: data with no inherent structure
  • (e) Polygonal Data (vtkPolyData)
  • irregular in both topology and geometry
  • examples: vertices, polyvertices, lines, polylines, polygons, triangle strips
  • applications: modelling
  • (f) Unstructured Grid (vtkUnstructuredGrid)
  • irregular in both topology and geometry
  • examples: any combination of cells
  • applications: finite element analysis, structural design, vibration

Data Attributes

VTK data objects also have attributes associated with the topological and geometrical organizing structure:

  • Scalars
  • single valued
  • examples: temperature, pressure, density, elevation
  • Vectors
  • magnitude and direction
  • examples: velocity, momentum
  • Normals
  • direction vectors (have a magnitude of 1)
  • used for shading
  • Texture Coordinates
  • used to map a point in Cartesian space into 1, 2, or 3D texture space
  • used for texture mapping of polygonal surfaces
  • volume visualization can use 3D textures
  • Tensors
  • rank 0 (scalar), rank 1 (vector), rank 2 (matrix), rank 3 (3D rectangular array)
  • examples: stress, strain

Scalar Visualization Algorithms

Scalars are single data values associated with each point/cell in the dataset. There are many different algorithms to visualize scalar data. Two common algorithms are Color Mapping and Contouring.

Color Mapping

In color mapping scalar values are mapped through a lookup table to a specific color. Scalar values are used as an index into a color lookup table. The primary VTK classes used for color mapping are vtkLookupTable and vtkDataSetMapper. The basic idea is to specify a HSVA (Hue-Saturation-Value-Alpha) ramp and then generate the colors in the table by using linear interpolation into the HSVA space. Using an instance of vtkLookupTable you can set both the number of colors (size of the table) and the hue range for the table. Several examples of using color mapping to visualize scalar data are located in the materials/Demos/ColorMaps directory. Here is example Tcl code which shows how to set up the color table and map the entire scalar range of the data into the color table:

vtkLookupTable lut
   lut SetNumberofColors 16
   lut SetHueRange 0.0 0.667
   lut Build

vtkStructuredGridReader reader
   reader SetFileName “Data/subset.vtk”
   reader Update

vtkDataSetMapper mapper
   mapper SetInputConnection [reader GetOutputPort]
   mapper SetLookupTable lut
   eval mapper SetScalarRange [[reader GetOutput] GetScalarRange]

vtkActor actors
   actor SetMapper mapper

This code is in the file materials/Demos/ColorMaps/colormap.numcolors.tcl. To run:

scc1% cd materials/Demos/ColorMaps
scc1% vtk colormap.numcolors.tcl

Instead of mapping the entire scalar range of the data into the color table, we can instead set a specific range (in terms of minimum and maximum) of the data that is mapped. Here is example Tcl code which shows the technique:

vtkLookupTable lut
   lut SetNumberofColors 256
   lut SetHueRange 0.0 0.667
   lut Build

vtkStructuredGridReader reader
   reader SetFileName “Data/subset.vtk”
   reader Update

vtkDataSetMapper mapper
   mapper SetInputConnection [reader GetOutputPort]
   mapper SetLookupTable lut
   mapper SetScalarRange 0.0 0.7

vtkActor actors
   actor SetMapper mapper

This code is in the file materials/Demos/ColorMaps/colormap.scalarrange.tcl. To run:

scc1% cd materials/Demos/ColorMaps
scc1% vtk colormap.scalarrange.tcl

And if you want more control over the color mapping, you can map individual scalar values to specific colors by manually inserting colors at specific locations in the table. Here is example Tcl code which shows the technique:

vtkLookupTable lut
   lut SetNumberofColors 256
   lut SetHueRange 0.0 0.667
   lut Build

set red {1.0 0.0 0.0}
set green {0.0 1.0 0.0}
set blue {0.0 0.0 1.0}
set alpha 1

for {set i 0} {$i<63} {incr i 1} {
   eval lut SetTableValue $i $red $alpha
}
for {set i 63} {$i<128} {incr i 1} {
   eval lut SetTableValue $i $green $alpha
}
for {set i 128} {$i<256} {incr i 1} {
   eval lut SetTableValue $i $blue $alpha
}

vtkStructuredGridReader reader
   reader SetFileName “Data/subset.vtk”
   reader Update

vtkDataSetMapper mapper
   mapper SetInputConnection [reader GetOutputPort]
   mapper SetLookupTable lut
   eval mapper SetScalarRange [[reader GetOutput] GetScalarRange]

vtkActor actors
   actor SetMapper mapper

This code is in the file materials/Demos/ColorMaps/colormap.table.tcl. To run:

scc1% cd materials/Demos/ColorMaps
scc1% vtk colormap.table.tcl

Contours / Isosurfaces
Contouring is a technique where one constructs a boundary between distinct regions in the data. Contours are lines or surfaces of constant scalar value. This is a natural extension from color mapping as our eyes instinctively separate similarly colored areas into distinct regions. The first step in contouring is to explore the data space to find points near a contour or region of interest. Once found these points are then connected into either contour lines (isolines) for two-dimensionsal data or into surfaces (isosurfaces) for three-dimensional data. The lines or surfaces can be color mapped using the scalar data. The primary VTK classes used for contouring are vtkContourFilter and vtkPolyDataMapper (vtkCountourFilter generates polygonal data). Several examples of using contours to visualize scalar data are located in the materials/Demos/Contours directory. Here is example Tcl code which shows how to generate contours for two-dimensional data:

vtkStructuredGridReader reader
   reader SetFileName “Data/subset.vtk”
   reader Update

vtkContourFilter contour
   contour SetInputConnection [reader GetOutputPort]
   contour SetValue 0 0.26

vtkPolyDataMapper contourMapper
   contourMapper SetInputConnection [contour GetOutputPort]
   eval contourMapper SetScalarRange
      [[reader GetOutput] GetScalarRange]

vtkActor contourActor
   contourActor SetMapper contourMapper

This code is in the file materials/Demos/Contours/contour.single.tcl. To run:

scc1% cd materials/Demos/Contours
scc1% vtk contour.single.tcl

You can also generate a series of contours over a range of data values. Here is example Tcl code which shows the technique:

vtkStructuredGridReader
reader
   reader SetFileName “Data/subset.vtk”
   reader Update

vtkContourFilter contour
   contour SetInputConnection [reader GetOutputPort]
   eval contour GenerateValues 10 [[reader GetOutput] GetScalarRange]

vtkPolyDataMapper contourMapper
   contourMapper SetInputConnection [contour GetOutputPort]
   eval contourMapper SetScalarRange
      [[reader GetOutput] GetScalarRange]

vtkActor contourActor
   contourActor SetMapper contourMapper

This code is in the file materials/Demos/Contours/contour.multi.tcl. To run:

scc1% cd materials/Demos/Contours
scc1% vtk contour.multi.tcl

For three-dimensional data we can generate an isosurface. We use exactly the same technique as used for generating contours in two-dimensional data. The only difference is we are reading in a three-dimensional dataset (density.vtk) instead of a two-dimensional dataset (subset.vtk). Here is example Tcl code which shows the technique:

vtkStructuredGridReader reader
   reader SetFileName “Data/density.vtk”
   reader Update

vtkContourFilter iso
   iso SetInputConnection [reader GetOutputPort]
   iso SetValue 0 0.26

vtkPolyDataMapper isoMapper
   isoMapper SetInputConnection [iso GetOutputPort]
   eval isoMapper SetScalarRange [[reader GetOutput] GetScalarRange]

vtkActor isoActor
   isoActor SetMapper isoMapper

This code is in the file materials/Demos/Contours/isosurface.tcl. To run:

scc1% cd materials/Demos/Contours
scc1% vtk isosurface.tcl

More examples are available in the materials/Demos/Contours directory. isosurface.colorbyVector.tcl and isosurface.colorbyScalar2.tcl show you how to color the isosurface using additional vector or scalar data.


Vector Visualization Algorithms

Vector data is a three-dimensional representation of direction and magnitude associated with each point/cell in the dataset. Vector data is often used to describe rate of change of some quantity. For example vectors can be used to describe fluid flow. There are several algorithms that can be used to visualize vector data.
Hedgehogs
One visualization technique for vector data is to draw an oriented, scaled line for each vector. The lines may be colored according to vector magnitude or some other scalar quantity (e.g. temperature or pressure). The result looks similar to a bristly hedgehog. Often you will need to adjust the scaling of the lines to control the size of its visual representation. The primary VTK class used for generating hedgehogs is vtkHedgeHog. Examples of using a hedgehogs to visualize vector data are located in the materials/Demos/Hedgehogs directory. Here is example Tcl code which shows how to generate a hedgehog from vector data:

vtkStructuredGridReader reader
   reader SetFileName “Data/density.vtk”
   reader Update

vtkHedgeHog hhog
   hhog SetInput [reader GetOutput]
   hhog SetScaleFactor 0.001

vtkPolyDataMapper hhogMapper
   hhogMapper SetInput [hhog GetOutput]
   hhogMapper SetLookupTable lut
   hhogMapper ScalarVisibilityOn
   eval hhogMapper SetScalarRange [[reader GetOutput] GetScalarRange]

vtkActor hhogActor
   hhogActor SetMapper hhogMapper

This code is in the file materials/Demos/ColorMaps/colormap.numcolors.tcl. To run:

scc1% cd materials/Demos/Hedgehogs
scc1% vtk hedgehog.tcl

Oriented Glyphs
A similar technique to using hedgehogs is to use oriented glyphs. Glyphs are polygonal objects such as a cone or an arrow and can be used in place of the lines in the hedgehogs. They too can be colored and scaled. The orientation and color of the glyph can indicate the direction and magnitude of the vector. The primary VTK class used for generating orientated glyphs is vtkGlyph3D. Examples of using a oriented glyphs to visualize vector data are located in the materials/Demos/Glyphs directory. Here is example Tcl code which shows how to use glyphs to visualize vector data:

vtkStructuredGridReader reader
   reader SetFileName “Data/subset.vtk”
   reader Update

vtkArrowSource arrow
   arrow SetTipResolution 6
   arrow SetTipRadius 0.1
   arrow SetTipLength 0.35
   arrow SetShaftResolution 6
   arrow SetShaftRadius 0.03

vtkGlyph3D glyph
   glyph SetInput [reader GetOutputPort]
   glyph SetSource [arrow GetOutputPort]
   glyph SetVectorModeToUseVector
   glyph SetColorModeToColorByScalar
   glyph SetScaleModeToDataScalingOff
   glyph OrientOn
   glyph SetScaleFactor 0.2

vtkPolyDataMapper glyphMapper
   glyphMapper SetInput [glyph GetOutput]
   glyphMapper SetLookupTable lut
   glyphMapper ScalarVisibilityOn
   eval glyphMapper SetScalarRange [[reader GetOutput] GetScalarRange]

vtkActor glyphActor
   glyphActor SetMapper contourMapper

This code is in the file materials/Demos/Glyphs/glyph.tcl. To run:

scc1% cd materials/Demos/Glyphs
scc1% vtk glyph.tcl

Streamlines
A streamline can be thought of as the path a massless particle takes flowing through a velocity field (i.e. vector field). Streamlines can be used to convey the structure of a vector field by providing a snapshot of the flow at a given instant in time. Multiple streamlines can be created to explore interesting features in the field. Streamlines are computed via numerical integration (integrating the product of velocity times delta T). Creating streamlines will require several VTK classes. First you will need to specify a starting point or points for the streamline(s). You can use either the VTK class vtkPointSource or vtkLineSource to create the starting points. Next you will need to pick an integrator such as vtkRungeKutta4 to do the numerical integration. Finally you will need to create a stream tracer using vtkStreamTracer. Examples of creating streamlines are located in the materials/Demos/Streamlines directory. Here is example Tcl code which shows the basic way of creating streamlines:

vtkStructuredGridReader reader
   reader SetFileName “Data/density.vtk”
   reader Update

vtkPointSource seeds
   seeds SetRadius 3.0
   eval seeds SetCenter [[reader GetOutput] GetCenter]
   seeds SetNumberOfPoints 100

vtkRungeKutta4 integ

vtkStreamTracer streamer
   streamer SetInputConnection  [reader GetOutputPort]
   streamer SetSourceConnection [seeds GetOutputPort]
   streamer SetMaximumPropagation 100
   streamer SetMaximumPropagationUnitToTimeUnit
   streamer SetInitialIntegrationStepUnitToCellLengthUnit
   streamer SetInitialIntegrationStep 0.1
   streamer SetIntegrationDirectionToBoth
   streamer SetIntegrator integ

vtkPolyDataMapper mapStreamLines
   mapStreamLines SetInputConnection [streamer GetOutputPort]
   eval mapStreamLines SetScalarRange [[reader GetOutput] GetScalarRange]

vtkActor streamLineActor
   streamLineActor SetMapper mapStreamLines

This code is in the file materials/Demos/Streamlines/streamLines.tcl. To run:

scc1% cd materials/Demos/Streamlines
scc1% vtk streamLines.tcl

More examples are available in the materials/Demos/Streamlines directory. streamRibbon.tcl shows you how to create ribbons instead of lines and streamTubes.varyRadius.tcl show you how to create tubes with varying radii.


Modeling Visualization Algorithms

Modeling algorithms change dataset geometry or topology. They are often used to reveal internal details of a data set. Two common modeling visualization techniques are cutting (slicing) and clipping.
Cutting/Slicing
Cutting also called slicing entails creating a “cross-section” of the dataset. Cutting uses an implicit function to define a surface with which to cut the dataset. Any type of implicit function may be used to create the surface. One simple technique is to use a plane to define the cutting surface thereby creating a planar cut. The cutting surface interpolates the data as it cuts and can be visualized using any of the standard visualization techniques. The result of cutting is always of type vtkPolyData. To create a planar cut we will need to create a plane using the class vtkPlane and we will need the VTK class vtkCutter to do the actual cutting. Examples of creating cutplanes are located in the materials/Demos/Cutplanes directory. Here is example Tcl code which shows how to generate a cutplane:

vtkStructuredGridReader reader
   reader SetFileName “Data/density.vtk”
   reader Update

vtkPlane plane
   eval plane SetOrigin [[reader GetOutput] GetCenter]
   plane SetNormal -0.287 0 0.9579

vtkCutter planeCut
   planeCut SetInputConnection
     [reader GetOutputPort]planeCut SetCutFunction plane

vtkPolyDataMapper cutMapper
   cutMapper SetInputConnection [planeCut GetOutputPort]
   eval cutMapper SetScalarRange [[reader GetOutput] GetScalarRange]

vtkActor cutActor
   cutActor SetMapper cutMapper

This code is in the file materials/Demos/Cutplanes/cutplane.tcl. To run:

scc1% cd materials/Demos/Cutplanes
scc1% vtk cutplane.tcl

Clipping
Clipping, like cutting, also uses an implicit function to define a surface. But instead of creating a cross-section of the dataset, clipping uses the surface to “cut” through the cells of the dataset, returning everything inside of the specified implicit function. The result of clipping is an unstructured grid. As we did with cutting in the previous example, to keep things simple we will also use a plane as our implicit function to create the surface for clipping the dataset. We will again create a plane using the class vtkPlane and we will use the VTK class vtkClipDataSet to do the actual clipping of the dataset. Example of using clipping are located in the materials/Demos/Clipping directory. Here is example Tcl code which shows how to set up clipping:

vtkStructuredGridReader reader
   reader SetFileName “Data/density.vtk”
   reader Update

vtkPlane plane
   eval plane SetOrigin [[reader GetOutput] GetCenter]
   plane SetNormal -0.287 0 0.9579

vtkClipDataSet clip
   clip SetInputConnection [reader GetOutputPort]
   clip SetClipFunction plane
   clip InsideOutOn

vtkDataSetMapper clipMapper
   clipMapper SetInputConnection [clip GetOutputPort]
   eval clipMapper SetScalarRange [[reader GetOutput] GetScalarRange]

vtkActor clipActor
   clipActor SetMapper clipMapper

This code is in the file materials/Demos/Clipping/clipping.tcl. To run:

scc1% cd materials/Demos/Clipping
scc1% vtk clipping.tcl

Additional Help

For more information on VTK, visit the VTK website or the VTK Wiki. The manual for version 5.4 of VTK is available online, along with an overview of the package. If you are just starting to learn VTK, we recommend that you get the VTK User’s Guide which is available from Kitware.
For specifics on running VTK on SCV systems see our VTK Help Page. Our installation of VTK comes with many VTK demo programs which are described on the VTK Examples web page.
As part of our 2008 Workshop on Scientific Visualization, a talk on VTK and ParaView (a GUI-based visualization application built on top of VTK) was presented which you might find useful.
An updated talk on Scientific Visualization using VTK was presented in February, 2010. Demos and data used in the tutorial are also available.
There are also several other VTK tutorials available online:

  1. How to Create Visualization Applications with VTK
  2. An introduction to Programming for Medical Image Analysis With the Visualization Toolkit
  3. Visualizing with VTK: A Tutorial (PDF)

References

The Visualization Toolkit, 3rd Edition, Will Schroeder, Pearson Education, Inc, 2002.

The VTK User’s Guide, 4.2 Edition, Kitware, 2003.

Kitware: www.vtk.org