VTK/FAQ

General information and availability

What is the Visualization Toolkit?

The Visualization ToolKit (vtk) is a software system for 3D Computer Graphics and Visualization.

VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit, An Object-Oriented Approach to 3D Graphics]), a C++ class library, and Tcl, Python and Java implementations based on the class library.

For more information, see http://www.vtk.org and http://www.kitware.com.

What is the current release?

The current release of vtk is 4.2. This release is available at:

http://www.vtk.org/files/release/4.2/

Nightly development releases are available at:

http://www.vtk.org/files/nightly/

See http://www.vtk.org/get-software.php for more information.

Can I contribute code or bug fixes?

We encourage people to contribute bug fixes as well as new contributions to the code. We will try to incorporate these into future releases so that the entire user community will benefit from them.

See http://www.vtk.org/contribute.php for information on contributing to VTK.

For some ideas take a look at some of the entries in the "Changes to the VTK API" FAQ section, for example: What changes are being considered for VTK

Can I contribute money?

Please don't send money. Not that we think you're going to send in unsolicited money. But if you were thinking about it, stop. It would just complicate our lives and make for all sorts of tax problems.

Is there a mailing list or Usenet newsgroup for VTK?

There is a mailing list: vtkusers@vtk.org

To subscribe or unsubscribe to the mailing list, go to: http://www.vtk.org/mailman/listinfo/vtkusers

To search the list archives go to: http://www.kitware.com/search.html

There is also a newsgroup that mirrors the mailinglist. At this point it seems that mirror is down. Mail to the mailinglist used to be posted the newsgroup, but posts on the newsgroup were not sent to the mailinglist. The newsgroup was located at: news://scully.esat.kuleuven.ac.be/vtk.mailinglist

Is the VTK mailing list archived anywhere?

The mailing list is archived at: http://www.vtk.org/pipermail/vtkusers/

You can search the archive at: http://www.kitware.com/search.html

Are answers for the exercises in the VTK book available?

Not anymore.

The answers to the exercises of the textbook used to be maintained by Martin Stoufer (kudos), and will be made available by Kitware in the next future.

Is VTK regression tested on a regular basis? Can I help?

Yes, it is.

You can view the current regression test results at: http://public.kitware.com/dashboard.php?name=vtk

VTK uses Dart to perform builds, run tests, and generate dashboards. You can find more information about Dart at: http://public.kitware.com/Dart/

You can help improve the quality of VTK by supplying the authors with Tcl scripts that can be used as or turned into regression tests. A good regression test will:

1. Cover code that is not already covered.
2. Illustrate a bug that is occuring now or that has occurred in the past.
3. Use data that is on the 2nd Edition book CDROM or use "small" data files or use no data at all.
4. Optionally, produce an interesting result.

Currently almost all regression tests are written in Tcl.

Please send your Tcl regression tests to: mailto:wlorens1@mail.nycap.rr.com

Bill will evaluate them for applicability and integrate them into the nightly test process.

What's the best way to learn VTK?

There are five things you might want to try:

1. Purchase the book The Visualization Toolkit from Kitware Inc.
2. Purchase the book VTK Users Guide from Kitware Inc.
3. Download the source code and/or binaries (available on Windows) and work through the examples (there are 400-500 examples).
4. To learn the innards of VTK, you can attend a VTK course or sponsor a VTK course at your site through Kitware. http://www.kitware.com/products/index.html
5. Buy Bill a beer and get him talking about VTK

How should I ask questions on the mailing lists?

The best online resource for this question is Eric S. Raymond's excellent guide on the topic titled "How to ask questions the smart way". Read it here:

http://www.catb.org/~esr/faqs/smart-questions.html

Please do read it and follow his advice. Thanks!

Please also remember the following when you post your messages to the VTK mailing lists.

• Mention the version of VTK you are using and the version of the compiler or scripting language you are using.

• Mention your platform, OS and their versions.

• Include hardware details if relevant.

• Include all relevant error messages (appropriately trimmed of course).

• The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.

• Avoid HTML emails.

• Use a sensible and descriptive subject line.

• Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.

• Quote the messages you reply to appropriately. Remove unnecessary details.

When asking a question or reporting a problem try to include a small example program that demonstrates the problem. Make sure that this example program is as small as you can make it, simple (and uses VTK alone), complete and demonstrates the problem adequately. Doing this will go a *long way* towards getting a quick and meaningful response.

Sometimes you might not get any acceptable response. This happens bacause the others think the question has either been already answered elsewhere (the archives, FAQ and google are your friends), or believe that you have not done enough homework to warrant their attention, or they don't know the answer or simply don't have the time to answer. Please do be patient and understanding. Most questions are answered by people volunteering their time to help you.

Happy posting!

Language bindings

Are there bindings to languages other than Tcl?

Aside from C++ (which it's written in) and Tcl, vtk is also bound into Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the Tcl/Java/Python wrapper code is generated from some LEX and YACC code that parses our classes and extracts the required information to generate the wrapper code.

What version of Tcl/Tk should I use with VTK?

Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the best-supported version combination at this time.

VTK has also been tested with Tcl/Tk 8.3.2 and works well.

Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more memory leaks that Tcl 8.3.2 has.

Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to change a couple of configuration settings depending on the version of VTK you are using. Check the Does VTK support Tcl/Tk 8.4?.

Where can I find Python 2.x binaries?

All of the Python binaries available on the kitware site are built for Python 1.5.2. This includes the official release VTK3.2 and the nightly builds (as at 2001-07-16).

For Python 2.x binaries, you will have to compile your own from source. It is worth checking the mailing list archives for comments by others who have been through this process.

There are some user-contributed binaries available at other sites. Check the mailing list archives for possible leads. Some win32 binaries for Python 2.1 are available at;

http://basic.netmeg.net/godzilla/

YMMV...

Why do I get the Python error -- ValueError: method requires a VTK object?

You just built VTK with Python support and everything went smoothly. After you install everything and try running a Python-VTK script you get a traceback with this error:

 ValueError: method requires a VTK object.

This error occurs if you have two copies of the VTK libraries on your system. These copies need not be in your linkers path. The VTK libraries are usually built with an rpath flag (under *nix). This is necessary to be able to test the build in place. When you install VTK into another directory in your linkers path and then run a Python script the Python modules remember the old path and load the libraries in the build directory as well. This triggers the above error since the object you passed the method was instantiated from the other copy.

So how do you fix it? The easiest solution is to simply delete the copy of the libraries inside your build directory or move the build directory to another place. For example, if you build the libraries in VTK/bin then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The error should no longer occur.

Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have to rebuild all of VTK, just delete the libraries (*.so files) and then re-run cmake and make. The only trouble with this approach is that you cannot have BUILD_TESTING to ON when you do this.

Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002) and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a special VTK-Python interpreter built as part of VTK called 'vtkpython' that should eliminate this problem. Simply use vtkpython in place of the usual python interpreter when you use VTK-Python scripts and the problem should not occur. This is because vtkpython uses the libraries inside the build directory.

2002 by Prabhu Ramachandran

Does VTK support Tcl/Tk 8.4 ?

Short answer: yes, but it might require some adjustments, depending on the VTK and CMake versions you are using.

1. The VTK 4.x CVS nightly/development distribution supports Tcl/Tk 8.4 as long as you use a release version of CMake > 1.4.5. Since VTK 4.2 will require CMake 1.6, the next release version will support Tcl/Tk 8.4.
2. The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.

In either cases, the following solutions will adress the problem. This basically involves setting two definition symbols that will make Tcl/Tk 8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard the "const correctness" and Tk_PhotoPutBlock compositing rule features) :

a) Edit your C/C++ flags:

Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake), display the advanced values and add the USE_NON_CONST and USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any of the following CMake variables (if they exist): CMAKE_CXX_FLAGS, CMAKE_C_FLAGS.

Example: On Unix your CMAKE_CXX_FLAGS will probably look like:

 -g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK

On Windows (Microsoft MSDev nmake mode):

 /W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK

b) or a more intrusive solution:

Edit the top VTK/CMakeList.txt file and the following lines add at the top of this file:

 ADD_DEFINITIONS(
   -DUSE_NON_CONST
   -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK
   )

Using VTK

What object/filter should I use to do ???

Frequently when starting out with a large visualization system people are not sure what object to use to achieve a desired effect.

The most up-to-date information can be found in the VTK User's Guide (http://www.kitware.com/products/vtkguide.html).

Alternative sources for information are the appendix of the book which has nice one line descriptions of what the different objects do and the VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).

Additionally, the VTK man pages feature a "Related" section that provide links from each class to all the examples or tests using that class (http://www.vtk.org/doc/nightly/html/pages.html). This information is also provided in each class man page under the "Tests" or "Examples" sub-section.

Some useful books are listed at http://www.vtk.org/buy-books.php

What 3D file formats can VTK import and export?

The following table identifies the file formats that VTK can read and write. Importer and Exporter classes move full scene information into or out of VTK. Reader and Writer classes move just geometry.

File Format	Read	Write
3D Studio	vtk3DSImporter
AVS "UCD" format	vtkAVSucdReader
Movie BYU	vtkBYUReader	vtkBYUWriter
Renderman		vtkRIBExporter
Open Inventor 2.0		vtkIVExporter/vtkIVWriter
CAD STL	vtkSTLReader	vtkSTLWriter
Fluent GAMBIT ASCII	vtkGAMBITReader
Unigraphics Facet Files	vtkUGFacetReader
Marching Cubes	vtkMCubesReader	vtkMCubesWriter
Wavefront OBJ		vtkOBJExporter
VRML 2.0		vtkVRMLExporter
VTK Structured Grid †	vtkStructuredGridReader	vtkStructuredWriter
VTK Poly Data †	vtkPolyDataReader	vtkPolyDataWriter
PLOT3D	vtkPLOT3DReader
CGM		vtkCGMWriter
OBJ	vtkOBJReader
Particle	vtkParticleReader
PDB	vtkPDBReader
PLY	vtkPLYReader	vtkPLYWriter
Gaussian	vtkGaussianCubeReader
XYZ	vtkXYZMolReader
Ensight ‡	vtkGenericEnSightReader

† See the books [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or the User's Guide for details about structured grid and poly data file formats.

‡ The class vtkGenericEnSightReader allows the user to read an EnSight data set without a priori knowledge of what type of EnSight data set it is (among vtkEnSight6BinaryReader, vtkEnSight6Reader, vtkEnSightGoldBinaryReader, vtkEnSightGoldReader, vtkEnSightMasterServerReader, vtkEnSightReader).

For any other file format you may want to search for a converter to a known VTK file format, more info on: http://www.tech-edv.co.at/lunix/UTILlinks.html

Why can't I find vtktcl (vtktcl.c)?

In versions of VTK prior to 4.0 VTK Tcl scripts would require a:

 catch {load vtktcl} 

so that they could be executed directly from wish. In VTK 4.0 the correct mechanism is to use:

 package require vtk

For people using versions earlier than 4.0, vtktcl is a shared library that is built only on the PC. Most examples used the "catch" notation so that they will work on UNIX and on the PC. On UNIX you must use the vtk executable/shell which should be in vtk/tcl/vtk.

Problems with vtkDecimate and vtkDecimatePro

vtkDecimate and vtkDecimatePro have been tested fairly heavily so all known bugs have been removed. However, there are three situations where you can encounter weird behavior:

1. The mesh is not all triangles. Solution: use vtkTriangleFilter to triangulate polygons.
2. The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use vtkCleanPolyData to link triangles.
3. Bad triangles are present: e.g., triangles with duplicate vertices such as (1,2,1) or (100,100,112), or (57,57,57), and so on. Solution: use vtkCleanPolyData.

How can I read DICOM files ?

VTK does not support the DICOM protocol/format directly, although VTK is able to read 2D and 3D raw files, i.e. slices or volumes (see vtkImageReader, vtkVolumeReader, and derived classes). Hence, one solution is to convert DICOM files to a suitable raw format.

DICOM is a huge protocol, thus we would suggest you to look for any existing converters before coding your own DICOM reader. Some of them are listed in the The Medical Image Format FAQ (Part 8): http://www.dclunie.com/medical-image-faq/html/part8.html

Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be used to convert medical images to raw format. This tool is a command line program and does not provide any GUI at the moment. http://dicom2.barre.nom.fr/

There is a special section dedicated to the VTK: http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"

The following page also provide links to several other DICOM converters: http://www.barre.nom.fr/medical/samples/index.html#links

Finally in VTK 4.4 you have access to a simple vtkDICOMImageReader [1]

For a more elaborate DICOM library that support compressed jpeg, go to [2]

How to handle large data sets in VTK

One of the challenges in VTK is to efficiently handle large datasets. By default VTK is tuned towards smaller datasets. For large datasets there are a couple of changes you can make that should yield a much smaller memory footprint (less swapping) and also improve rendering performance. The solution is to:

1. Use ReleaseDataFlag,
2. Turn on ImmediateModeRendering
3. Use triangle strips via vtkStripper
4. Use a different filter or mapper

Each of these will be discussed below.

1) Using ReleaseDataFlag

By default VTK keeps a copy of all intermediate results between filters in a pipeline. For a pipeline with five filters this can result in having six copies of the data in memory at once. This can be controlled using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is set to one on a data object, then once a filter has finished using that data object, it will release its memory. Likewise, if GlobalReleaseDataFlag is set on ANY data object, all data objects will release their memory once their dependent filter has finished executing. For example in Tcl and C++

 # Tcl
 vtkPolyDataReader reader
 [reader GetOutput] ReleaseDataFlagOn

 // C++
 vtkPolyDataReader *reader = vtkPolyDataReader::New();
 reader->GetOutput()->ReleaseDataFlagOn();

or

 // C++
 vtkPolyDataReader *reader = vtkPolyDataReader::New();
 reader->GetOutput()->GlobalReleaseDataFlagOn();

While turning on the ReleaseDataFlag will reduce your memory footprint, the disadvantage is that none of the intermediate results are kept in memory. So if you interactively change a parameter of a filter (such as the isosurface value), all the filters will have to re-execute to produce the new result. When the intermediate results are stored in memory, only the downstream filters would have to re-execute.

One hint for good interactive performance. If only one stage of the pipeline can have its parameters changed interactively (such as the target reduction in a decimation filter), only retain the data just prior to that step (which is the default) and turn ReleaseDataFlag on for all other steps.

2) Use ImmediateModeRendering

By default, VTK uses OpenGL display lists which results in another copy of the data being stored in memory. For most large datasets you will be better off saving memory by not using display lists. You can turn off display lists by turning on ImmediateModeRendering. This can be controlled on a mapper by mapper basis using ImmediateModeRendering, or globally for all mappers in a process by using GlobalImmediateModeRendering. For example:

 # Tcl
 vtkPolyDataMapper mapper
 mapper ImmediateModeRenderingOn

 // C++
 vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();
 mapper->ImmediateModeRenderingOn();

or

 // C++
 vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();
 mapper->GlobalImmediateModeRenderingOn();

The disadvantage to using ImmediateModeRendering is that if memory is not a problem, your rendering rates will typically be slower with ImmediateModeRendering turned on.

3) Use triangle strips via vtkStripper.

Most filters in VTK produce independent triangles or polygons which are not the most compact or efficient to render. To create triangle strips from polydata you can first use vtkTriangleFilter to convert any polygons to triangles (not required if you only have triangles to start with) then run it through a vtkStipper to convert the triangles into triangle strips. For example in C++

 vtkPolyDataReader *reader = vtkPolyDataReader::New();
 reader->SetFileName("yourdatafile.vtk");
 reader->GetOutput()->ReleaseDataFlagOn();
 
 vtkTriangleFilter *tris = vtkTriangleFilter::New();
 tris->SetInput(reader->GetOutput());
 tris->GetOutput()->ReleaseDataFlagOn();

 vtkStripper *strip = vtkStripper::New();
 strip->SetInput(tris->GetOutput());
 strip->GetOutput()->ReleaseDataFlagOn();

 vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();
 mapper->ImmediateModeRenderingOn();
 mapper->SetInput(tris->GetOutput());

The only disadvantage to using triangle strips is that they require time to compute, so if your data is changing every time you render, it could actually be slower.

4) Use a different filter or mapper

This is a tough issue. In VTK there are typically a couple of ways to solve any problem. For example an image can be rendered as a polygon for each pixel, or it can be rendered as a single polygon with a texture map on it. For almost all cases the second approach will be much faster than the first event though VTK supports both. There isn't a single good answer for how to find the best approach. If you suspect that it is running more slowly than it should, try posting to the mailing list or looking for other ways to achieve the same result.

VTK is slow, what is wrong?

We have heard people say that VTK is really slow. In many of these cases, changing a few parameters can make a huge difference in performance.

If you find that VTK is slower than other visualization systems running the same problem first take a look at the FAQ section dealing with large data: How to handle large data sets in VTK. Many of its suggestions will improve VTK's performance significantly for many datasets.

If you still find VTK slow, please let us know and send us an example (to mailto:kitware@kitware.com). In the past there have been some filters that simply were not written to be fast. When we come across one of these we frequently can make minor changes to the filter that will make it run much more quickly. In fact many changes in the past couple years have been this type of performance improvement.

Is VTK thread-safe ?

The short answer is no.

Many VTK sources and filters cache information and will not perform as expected when used in multiple threads. When writing a multithreaded filter, the developer has to be very careful about how she accesses data.

For example, GetXXX() methods which return a pointer should only be used to read. If the pointer returned by these methods are used to change data in multiple threads (without mutex locks), the result will most probably be wrong and unpredictable. In many cases, there are alternative methods which copy the data referred by the pointer. For example:

 float* vtkDataArray::GetTuple(const vtkIdType i);

is thread-safe only for reading whereas:

 void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);

copies the requested tuple and is thread safe even if tuple is modified afterwards (as long as the same pointer is not passed as the argument tuple simultaneously by different threads).

Unfortunately, only very few methods are clearly marked as thread-(un)safe and, in many situations, the developer has to dig into the source code to figure out whether an accessor is thread safe or not.

vtkDataSet and most of it's sub-classes are well documented and almost all methods are marked thread-safe or not thread-safe. This might be a good place to start. Most of the filters in imaging and some filters in graphics (like vtkStreamer) are good examples of how a multi-threaded filter can be written in VTK.

However, if you are not interested in developing multithreaded filters but want to process some data in parallel using the same (or similar) pipeline, your job is much easier. To do this, create a different copy of the pipeline on each thread and execute them in parallel on a different piece of the data. This is best accomplished by using vtkThreadedController (instead of vtkMultiThreader). See the documentation of vtkMultiProcessController and vtkThreadedController and the examples in the parallel directory for details on how this can be done.

Also, note that most of the OpenGL libraries are not thread-safe. Therefore, if you are rendering to multiple render windows from different threads, you are likely to get in trouble, even if you have mutex locks around the render calls.

Can I use STL with VTK?

As of VTK version 4.2, you can use STL. However, the following policy applies.

1. STL is for implementation, not interface. All STL references should be contained in a .cxx class or the private section of the .h header file.
2. Use the PIMPL idiom to forward reference/contain STL classes in heavily used superclasses. STL is big, fat, and slow to compile so we do not want to include STL headers in any .h files that are included by most of VTK, e.g. vtkObject.h vtkSource.h etc.
3. Use the vtkstd:: namespace to refer to STL classes and functions.

Here's an example (from vtkInterpolateVelocityField):

In the .h file (the PIMPL) forward declare

class vtkInterpolatedVelocityFieldDataSetsType;
//
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet
{
private:
  vtkInterpolatedVelocityFieldDataSetsType* DataSets;
};

In the .cxx file define the class (here deriving from the STL vector container)

typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase
{};

In the .cxx file construct and destruct the class:

vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()
{
  this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;
}
                                                                    //
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()
{
  delete this->DataSets;
}

And in the .cxx file use the container as you would any STL container:

for ( DataSetsTypeBase::iterator i = this->DataSets->begin();
      i != this->DataSets->end(); ++i)
  {
  ds = i->GetPointer();
  ....
  }

What image file formats can VTK read and write?

The following table identifies the image file formats that VTK can read and write.

Image File	Read	Write
Bitmap	vtkBMPReader	vtkBMPWriter
Digital Elevation Model (DEM)	vtkDEMReader
DICOM	vtkDICOMImageReader
GE Signal	vtkGESignaReader
JPEG	vtkJPEGReader	vtkJPEGWriter
Binary UNC meta image data	vtkMetaImageReader	vtkMetaImageWriter
PNG	vtkPNGReader	vtkPNGWriter
PNM	vtkPNMReader	vtkPNMWriter
PostScript	vtkPostScriptWriter
SLC	vtkSLCReader
TIFF	vtkTIFFReader	vtkTIFFWriter
RAW files †	vtkImageReader, vtkVolumeReader

† A typical example of use is:

# Image pipeline
reader = vtkImageReader()
reader.SetDataByteOrderToBigEndian()
reader.SetDataExtent(0,511,0,511,0,511)
reader.SetFilePrefix("Ser397")
reader.SetFilePattern("%s/I.%03d")
reader.SetDataScalarTypeToUnsignedShort()
reader.SetHeaderSize(5432)

Printing an object.

Sometimes when debugging you need to print an object to a string, either for logging purposes, or in the case of windows applications, to a window.

Here is a way to do this:

std::ostringstream os;
//
// "SomeVTKObject" could be, for example, 
// declared somewhere as: vtkCamera *SomeVTKObject;
//
SomeVTKObject->Print(os);
vtkstd::string str = os.str();
//
// Process the string as you want

Platform-specific questions

What platforms does vtk run on?

VTK should compile and run on most versions of Unix, Linux and Windows. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows workstations. It was also succesfully built on MacOS X.

How do I build the examples on the PC running Windows?

Since building the C++ examples on the PC isn't all that easy, here are some instructions from Jack McInerney.

Steps for creating a VTK C++ project 8/14/96

This is based on what I learned creating a project to run the Mace example. These steps allowed me to successfully built and run this example.

1. Create a console project (File, New, then select Console application).
2. Add the files of interest to the project. (e.g., Mace.cxx)
3. Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies
   For this to work, Visual C++ needs to know where to look to find the include files. In my case they are at C:\VTK\VTK12SRC\INCLUDE. To tell Visual C++ to look there, go to Tools, Options. Select the tab Directories. Under the list for Include files add: C:\VTK\VTK12SRC\INCLUDE
4. Compile the file Mace.cxx. This will lead to many warnings about data possibly lost as double variables are converted to float variables. These can be gotten rid of by going to Build, Settings, and select the C++ tab. Under the General catagory, set Warning Level to 1* (instead of 3).
5. Before linking, some additional settings must be modified. Go to Build, Settings, and select the Link tab. In the General catagory, add the libraries opengl32.lib and glaux.lib to the Object/Library Modules. Put a space between each file name. Then select the C++ tab and the Category: Code Generation. Under Use Run-Time Library, select Debug Multithreaded DLL. Select OK to exit the dialog box. The above libraries are available from Microsoft's Web site at: http://www.microsoft.com/softlib/mslfiles/Opengl95.exe or ftp://ftp.microsoft.com/softlib/mslfiles/Opengl95.exe
   This is a self extracting archive which contains these files. Simply place them in your windows system directory.
6. Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless
   

When you go to run the program, it will bomb out unless it can find 2 DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the project directory or the C:\WINDOWS directory. These files are supplied on the vtk CD-ROM (in the vtk\bin directory).

64-bit System Issues

vtk does run on the DEC Alpha but vtk binary files are not compatible between 32-bit and 64-bit systems. For portability, use the default file type, ascii, for vtkPolyDataWriter, etc. You may be able to write a binary file on a 64-bit system and read it back in.

What size swap space should I use on a PC?

Building vtk on the PC requires a significant amount of memory (at least when using Visual C++)... but the final product is nice and compact. To build vtk on the PC, we recommend setting the min/max swap space to at least 400MB/500MB (depending on how much RAM you have... the sum of RAM and swap space should be roughly 500+ MB).

Are there any benchmarks of VTK and/or the hardware it runs on?

Take a look at the "Simple Sphere Benchmark":

http://www.barre.nom.fr/vtk/bench.html

It is not a "real world" benchmark, but provide synthetic results comparing different hardware running VTK:

http://purl.oclc.org/NET/rriv/vtk/sphere-bench

Why is XtString undefined when using VTK+Python on Unix?

This is a side effect of dynamic linking on (some?) Unix systems. It appears often on Linux with the Mesa libraries at least. The solution is to make sure your Mesa libraries are linked with the Xt library. One way to do this is to add "-lXt" to MESA_LIB in your user.make file.

How do I get the Python bindings to work when building VTK with Borland C++?

If you've built VTK with the freely downloadable Borland C++ 5.5 (or its commercial counterpart) and you're using the Python binaries from http://www.python.org/, you'll note that when you try to run a VTK Python example you get something similar to the following error message:

from vtkCommonPython import *                                
ImportError: dynamic module does not define init function
(initvtkCommonPython)

This is because BCC32 prepends an underscore ("_") to all exported functions, so (in this case) the vtkCommonPython.dll contains a symbol _initvtkCommonPython which Python does not find. All kits (e.g. Rendering, Filtering, Patented) will suffer from this problem.

The solution is to create Borland module definition in the VTK binary (output) directory, in my case VTK/bin. You have to do this for all kits that you are planning to use in Python. Each .def file must have the same basename as the DLL, e.g. "vtkCommonPython.def" for vtkCommonPython.dll and it must be present at VTK link time. The def file contains an export alias, e.g.:

EXPORTS
initvtkCommonPython=_initvtkCommonPython

The Borland compiler will create an underscore-less alias in the DLL file and Python will be able to load it as a module.

How do I build Python bindings on AIX ?

There is a problem with dynamic loading on AIX. Old AIX did not have dlopen/dlsym, but they used load mechanism. Python still reflects this. VTK is however not compatible with the old load mechanism.

The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX 5 or greater.

http://www.vtk.org/files/misc/python_aix.diff

How to build VTK for offscreen rendering?

Struggled a few hours to get VTK to do offscreen rendering. I use it to batch process medical images. Without actually producing output on the screen, I still print resulting images in a report to easily review the results of an experiment.

Here is how I solved this problem for VTK version 4.2.2.

1. Download Mesa-4.0.4 source

Modify Mesa-4.0.4/Make-config in the 'linux:' target the following vars:

GL_LIB = libVTKMesaGL.so
GLU_LIB = libVTKMesaGLU.so
GLUT_LIB = libVTKMesaglut.so
GLW_LIB = libVTKMesaGLw.so
OSMESA_LIB = libOSVTKMesa.so
CFLAGS = -O -g -ansi -pedantic -fPIC -ffast-math-DUSE_MGL_NAMESPACE \
         -D_POSIX_SOURCE -D_POSIX_C_SOURCE=199309L-D_SVID_SOURCE \
         -D_BSD_SOURCE -DUSE_XSHM -DPTHREADS -I/usr/X11R6/include"

then

  make -f Makefile.X11 linux  
  cp Mesa-4.0.4/lib/* /data/usr/mesa404/lib/

I use 'VTKMesa' name extension to avoid conflicts with my RH9.0 libs (especially OSMesa lib in XFree!). I'm using shared libraries, because that allows me to use dynamic libs from VTK and not the vtk program itself without explicitly having to load VTKMesaGL with my app. I copied the 'VTKMesa' libs in /data/usr/mesa404/lib/, but any odd place probably will work. Avoid /usr/lib /usr/local/lib for now.

2. Follow normal instructions to get a proper working vtk, then

 ccmake 

with the following options:

VTK_USE_MANGLED_MESA	ON
MANGLED_MESA_INCLUDE_DIR	/data/usr/mesa404/include
MANGLED_MESA_LIBRARY	/data/usr/mesa404/lib/libVTKMesaGL.so
MANGLED_OSMESA_INCLUDE_DIR	/data/usr/mesa404/include
MANGLED_OSMESA_LIBRARY	/data/usr/mesa404/lib/libOSVTKMesa.so
OPENGL_xmesa_INCLUDE_DIR	/data/usr/mesa404/include

test using /data/prog/VTK-4.2.2/Examples/MangledMesa/Tcl scripts

Changes to the VTK API

Change to vtkIdList::IsId()

vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the specified id is in the list. Now it returns -1 if the id is not in the list; or a non-negative number indicating the position in the list.

Changes vtkEdgeTable

vtkEdgeTable had two changes. The constructor now takes no arguments, and you use InitEdgeInsertion() to tell the class how many points are in the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined by points p1,p2) is not defined. otherwise a non-negative integer value is returned.

These changes were made to support the association of attributes with edges.

Changes between VTK 4.2 and VTK 4.4 (and how to update)

We have removed the CVS date, revision, and the language from the copyright on all the files. This information wasn't being used much and it created extra work for developers. For example you edit vtkObject.h rebuild all of VTK, check in you change, then you must rebuild all of VTK again because commiting the header file causes it to be changed by CVS (because the revision number changed) This change will also make it easier to compare different branches of VTK since these revision number differences will no longer show up. The CVS revision number is still in the cxx file in the RevisionMacro. You don't need to make any changes to your code for this.

The DataArray classes now use a templated intermediate class to share their implementation. Again there is no need for you to make changes to your code.

Legacy code has been removed. Specifically none of the old style callbacks are supported and observers should be used instead. So where you used a filter->SetStartMethod(myFunc) you should do a filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will require you to create a small class for the observer. vtkImageOpenClose3D.cxx has an example of using an observer and there are a few other examples in VTK. If you switch to using Observers your code should also work with versions of VTK from 3.2 or later since the Observers have been in VTK since VTK 3.2.

Many functions that previously took or returned float now take or return double. To change your code to work with VTK 4.4 or later you can just replace float with double for the appropriate calls and variables. If you want your code to work with both old and new versions of VTK you can use vtkFloatingPointType which is defined to be double in VTK 4.4 and later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5 you can use something like:

#ifndef vtkFloatingPointType
#define vtkFloatingPointType vtkFloatingPointType
typedef float vtkFloatingPointType;
#endif

at the beginning of your code. That will set it to the correct value for all versions of VTK old and new.

Use of New() and Delete() now enforced (vs. new & delete)

Constructors and destructors in VTK are now protected. This means you can no longer use little "new" or "delete" to create VTK instances. You'll have to use the methods ::New() and ::Delete() (as has been standard practice for some time).

The reason for this is to enforce the use of New() and Delete(). Not using New() and Delete() can lead to bad mojo, mainly reference counting problems or not taking advantage of special procedures incorporated into the New() method (e.g., selecting the appropriate hardware interface during instance creation time).

If you've used New() and Delete() in your code, these changes will not affect you at all. If you're using little "new" or "delete", your code will no longer and compile and you'll have to switch to New() and Delete().

Changes between VTK 4.4 and VTK 4.6

Collection Changes

Collections have had some small changes (originally started by Chris Volpe) to better support reentrant iteration. Specifically all the collection have an InitTraversal(sit) and GetNextFoobar(sit) methods. (where Foobar is what the collection contains, for example GetNextActor(sit)) The argument to both of these methods is a vtkCollectionSimpleIterator. Most of the collection use in VTK has been modified to use these new methods. The advantage is that these new methods support having the same collection be iterated through in a reentrant safe manner. In the past this was not true and led to a number of problems. In the future for C++ class development please use this approach to iterating through a collection. These changes are fully backwards compatible and no old APIs were harmed in the making of these changes. So in summary, for the future, where you would have written:

for (actors->InitTraversal();
     (actor = actors->GetNextActor());)

you would now have:

 vtkCollectionSimpleIterator actorIt;
 for (actors->InitTraversal(actorIt);
      (actor = actors->GetNextActor(actorIt));)

Changes in VTK between 3.2 and 4.0

• Changes to vtkDataSetAttributes, vtkFieldData and vtkDataArray: All attributes (scalars, vectors...) are now stored in the field data as vtkDataArray's. vtkDataSetAttributes became a sub-class of vtkFieldData. For backwards compatibility, the interface which allows setting/getting the attributes the old way (by passing in a sub-class of vtkAttributeData such as vtkScalars) is still supported but it will be removed in the future. Therefore, the developers should use the new interface which requires passing in a vtkDataArray to set an attribute. vtkAttributeData and it's sub-classes (vtkScalars, vtkVectors...) will be deprectated in the near future; developers should use vtkDataArray and it's sub-classes instead. We are in the process of removing the use of these classes from vtk filters.

• Subclasses of vtkAttributeData (vtkScalars, vtkVectors, vtkNormals, vtkTCoords, vtkTensors) were removed. As of VTK 4.0, vtkDataArray and it's sub-classes should be used to represent attributes and fields. Detailed description of the changes and utilities for upgrading from 3.2 to 4.0 can be found in the package: http://www.vtk.org/files/misc/Upgrading.zip

• Added special methods to data arrays to replace methods like

 tc SetTCoord i x y 0

or

 vc SetVector i vx vy vz

in interpreted languages (Tcl, Python, Java). Use:

 tc SetTuple2 i x y

or

 vc SetTuple3 i vx vy vz

• Improved support for parallel visualization: vtkMultiProcessController and it's sub-classes have been re-structured and mostly re-written. The functionality of vtkMultiProcessController have been re-distributed between vtkMultiProcessController and vtkCommunicator. vtkCommunicator is responsible of sending/receiving messages whereas vtkMultiProcessController (and it's subclasses) is responsible of program flow/control (for example processing rmi's). New classes have been added to the Parallel directory. These include vtkCommunicator, vtkMPIGroup, vtkMPICommunicator, vtkSharedMemoryCommunicator, vtkMPIEventLog... There is now a tcl interpreter which supports parallel scripts. It is called pvtk and can be build on Windows and Unix. Examples for both Tcl and C++ can be found in the examples directories.

• vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.

• Since it was causing very long compile times (it essentially includes every vtk header file) and it was hard to maintain (you had to add a line whenever you added a class to VTK) vtk.h was removed. You will have to identify the header files needed by your application and include them one by one.

• vtkIterativeClosestPointTransform has been added. This class is an implementation of the ICP algorithm. It matches two surfaces using the iterative closest point (ICP) algorithm. The core of the algorithm is to match each vertex in one surface with the closest surface point on the other, then apply the transformation that modify one surface to best match the other (in a least square sense).

• The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.

• Support for reading and writing PGM and JPEG images has been included.

• Methods with parameters of the form "type param[n]" are wrapped. Previously, these methods were only wrapped if the array was declared 'const'. The python wrappers will allow values to be returned in the array.

• The directory structure was completely reorganized. There are now subdirectories for Common (core common classes) Filtering (superclasses for filtering operations) Imaging (filters and sources that produce images or structured points) Graphics (filters or sources that produce data types other than ImageData and StructuredPoints) IO (file IO classes that do not require Rendering support) Rendering (all actors mappers annotation and rendering classes) Hybrid (typically filters and sources that require support from Rendering or both Imagign and Graphics) Parallel (parallel visualization support classes) Patented (patented classes) Examples (documented examples) Wrapping (support for the language wrappers). In many directories you will see a Testing subdirectory. The Testing subdirectories contain tests used to validate VTKs operation. Some tests may be useful as examples but they are not well documented.

• The Build process for VTK now uses CMake (found at www.cmake.org) This replaces pcmaker on windows and configure on UNIX. This resolves some longstanding problems and limitation we were having with pcmaker and configure, and unifies the build process into one place.

Changes to VTK between 4.0 and 4.2

• Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.

• Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).

• vtkImageWindow, vtkImager, vtkTkImageWindowWidget and their subclasses have been removed to reduce duplicated code and enable interation in ImageWindows. Now people should use vtkRenderer and vtkRenderWindow instead. vtkImageViewer still works as a turn key image viewing class although it now uses vtkRenderWindow and vtkRenderer internally instead of vtkImageWindow and vtkImager.

• New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.

• Event processing: Several new events to VTK were added (see vtkCommand.h). Also event processing can now be prioritized and aborted. This allows applications to manage who processes which events, and terminates the processing of a particular event if desired.

• 3D Widgets: A new class vtkInteractorObserver was added to observe events on vtkRenderWindowInteractor. Using the new event processing infrastructure, multiple 3D widgets (subclasses of vtkInteractorObserver) can be used simultaneously to process interactions. Several new 3D widgets have been added including:
  • vtkLineWidget
  • vtkPlaneWidget
  • vtkImagePlaneWidget
  • vtkBoxWidget
  • vtkSphereWidget

• Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.

• New class: vtkInstantiator provides a means by which one can create an instance of a VTK class using only the name of the class as a string.

• New class: vtkXMLParser provides a wrapper around the Expat XML parsing library. A new parser can be written by subclassing from vtkXMLParser and providing a few simple virtual method implementations.

• TIFF reader is now implemented using libtiff, which makes it capable of reading almost all available TIFF formats. The libtiff is also available internally as vtktiff.

• New method (all sub-classes of vtkObject): Added a virtual function called NewInstance to vtkTypeMacro. NewInstance creates and returns an object of the same type as the current one. It does not copy any properties. The returned pointer is of the same type as the pointer the method was invoked with. This method should replace all the MakeObject methods scattered through VTK.

• vtkSetObject macro is depricated for use inside the VTK. It is still a valid construct in projects that use VTK. Instead use vtkCxxSetObjectMacro which does the same thing.

• vtkPLOT3DReader have been improved. It now supports:
  • multigrid (each block is one output)
  • ascii
  • fortran-style byte counts
  • little/big endian
  • i-blanking (partial)

• A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the

Text properties in VTK 4.2 FAQ entry for a full description of the change.

How do I upgrade my existing C++ code from 3.2 to 4.x?

This is (a corrected version of) an email that was posted to vtkusers. Please feel free to correct or add anything.

I've just ported my medium-sized (40K lines) application from vtk3.2 to vtk4.x. I thought I would share my experiences with you, in case there were people out there contemplating it but a bit scared. One source of information for upgrading code is: http://www.vtk.org/files/misc/Upgrading.zip I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the script in the zip file. So, I switched all my include directories to the new VTK ones and recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and vtkTCoords which have both been removed. Where I was using single value scalars, like this: vtkScalars *scalars = vtkScalars::New(); scalars->SetNumberOfScalars(N_POINTS); ... polydata->GetPointData()->SetScalars(scalars); ... scalars->SetScalar(i,2.3); ... I replaced with: vtkFloatArray *scalars = vtkFloatArray::New(); scalars->SetNumberOfComponents(1); scalars->SetNumberOfTuples(N_POINTS); ... polydata->GetPointData()->SetScalars(scalars); ... scalars->SetTuple1(i,2.3); ... OK so far, far fewer errors. Where I had 2D texture coordinates: vtkTCoords *tcoords = vtkTCoords::New(); tcoords->SetNumberOfTCoords(N); ... float p[3]; p[0]=x; p[1]=y; tcoords->SetTCoord(i,p); ... I replaced with: vtkFloatArray *tcoords = vtkFloatArray::New(); tcoords->SetNumberOfComponents(2); tcoords->SetNumberOfTuples(N); ... float p[2]; p[0]=x; p[1]=y; tcoords->SetTuple(i,p); .... All well and good, still fewer errors. Make sure you call SetNumberOfComponents *before* SetNumberOfTuples else you'll get problems (I did!). Where I was creating 0-255 image data and had been using: vtkScalars* scalars = vtkScalars::New(); scalars->SetDataTypeToUnsignedChar(); ... I replaced with: vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New() ... Going well! When creating RGB images, I had been using: vtkScalars *scalars = vtkScalars::New(); scalars->SetDataTypeToUnsignedChar(); scalars->SetNumberOfComponents(3); scalars->SetNumberOfScalars(X*Y); ... scalars->SetActiveComponent(0); scalars->SetScalar(i,val1); scalars->SetActiveComponent(1); scalars->SetScalar(i,val2); scalars->SetActiveComponent(2); scalars->SetScalar(i,val3); ... I replaced with: vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New() scalars->SetNumberOfComponents(3); scalars->SetNumberOfTuples(X*Y); ... scalars->SetComponent(i,0,val1); scalars->SetComponent(i,1,val2); scalars->SetComponent(i,2,val3); ... My remaining errors concerned vtkWin32OffscreenRenderWindow that has been removed. Where I had been using: vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New(); ... I replaced with: vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New(); offscreen->SetOffScreenRendering(1); ... All done. I'd had to throw in some #include "vtkFloatArray.h" and things like that of course. Zero compile errors. Had to remember to link against the new vtk lib files, so I removed vtkdll.lib and added vtkCommon.lib vtkGraphics.lib etc. Zero link errors. My program is up and running again, no apparant problems. Plus now I can use all the new features of vtk4. (And I'm sure it's faster but maybe that's my imagination.) All this took me about three hours. Bye! Tim.

What is the release schedule for VTK

VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December of 2001 and released in March 2002. VTK 4.2 was releaseed in February of 2003. The next version of VTK will probably be released in late 2003 or early 2004.

Roadmap: What changes are being considered for VTK

This is a list of changes that are being considered for inclusion into VTK. Some of these changes will happen while other changes we would like to see happen but may not due to funding or time issues. For each change we try to list what the change is, when we hope to complete it, if it is actively being developed. Detailed discussion on changes is limited to the vtk-developers mailing list.

1. Modify existing image filters to use the new vtkImageIterator etc. Most simple filters have been modified to use ithe iterator in VTK 4.2. It would be nice to have some sort of efficient neighborhood iterators but so far we haven't come up with any.
2. Update vtkCollections to support an iterator. Currently vtkCollections do not work well because they store state for the current item. So two methods cannot work on the same collection in the same stack trace using the GetNextItem() interface. An iterator of some sort should be used instead. No one is working on this yet.
3. Support for AMR (mulit-res grids see http://seesar.lbl.gov/AMR/Overview/ for an overview)
4. Improvements to the pipeline update mechanism including support for multiresolution
5. Possible support for multi-block and composite grids
6. Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:
   • Make UnstructuredGrid more compact by removing the cell point count from the vtkCellArray. This will reduce the storage required by each cell by 4 bytes.
   • Make vtkPolyData an empty subclass of vtkUnstructuredGrid. There are a number of good reasons for this but it is a tricky task and backwards compatibility needs to be maintained.
7. More parallel support, including parallel compositing algorithms
8. Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms
9. Further integration of STL and other important C++ constructs (like templates)
10. Unstructured grid volume rendering

VTK 4.4 (intermediate release, end of 2003)

• convert APIs to double
• remove old callbacks
• blanking
• ref count observers (done)
• switch collections to use iterators
• improve copyright (done)

VTK 5.0 (major release, end of August 2004)

• new pipeline mechanism (see Media:Pipeline.pdf)
• time support
• true AMR support

Changes to Interactors

The Interactors have been updated to use the Command/Observer events of vtk. The vtkRenderWindowInteractor now has ivars for all the event information. There is a new class called vtkGenericRenderWindowInteractor that can be used to set up the bindings from other languages like python, Java or TCl.

A new class vtkInteractorObserver was also added. It has a SetInteractor() method. It observes the keypress and delete events invoked by the render window interactor. The keypress activation value for a widget is now 'i' (although this can be programmed). vtkInteractorObserver has the state ivar Enabled. All subclasses must have the SetEnabled(int) method. Convenience methods like On(), Off(), EnabledOn(), and EnabledOff() are available. The state of the interactor observer is obtained using GetEnabled(). The SetEnabled(1) method adds observers to watch the interactor (appropriate to the particular interactor observer) ; SetEnabled(0) removes the observers . There are two new events: EnableEvent and DisableEvent which are invoked by the SetEnabled() method.

The events also support the idea of priority now. When you add an observer, you can specify a priority from 0 to 1. Higher values will be called back first. An observer can also tell the object not to call any more observers. This way you can handle an event, and stop further processing. In this way you can add handlers to InteractorStyles without sub-classing and from wrapped languages.

For more information see: vtkGenericRenderWindowInteractor, vtkRenderWindowInteractor, vtkInteractorObserver.

Header files and vtkSetObjectMacro

On some platforms such as MS Visual Studio .NET, compiler is not capable of handling too big input files. Some VTK files with all includes do become big enough to overwhelm the compiler. The solution is to minimize the amount of includes. This especially goes for header files, because they propagate to other files. Every class header file should include only the parent class header file. If there is no other alternative, you should put a comment next to include file explaining why the file has to be included.

The related issue is with vtkSetObjectMacro. This file calles some methods on an argument class, which implies that the argument class header file has to be included. The result is bloat on the header files. The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro. The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not in the header file.

Example: Instead of

#include "vtkBar.h"
class vtkFoo : public vtkObject
{ ...
  vtkSetObjectMacro(Bar, vtkBar);
  ...
};

Do:

class vtkBar;
class vtkFoo : public vtkObject
{
  ...
  virtual void SetBar(vtkBar*);
  ...
};

and add the following line to vtkFoo.cxx

vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);

Text properties in VTK 4.2

A new vtkTextProperty class has been added to VTK 4.2.

This class factorizes text attributes that used to be spread out and duplicated in many different classes (mostly 2D actors and text mappers). Among those attributes, font family, font size, bold/italic/shadow properties, horizontal and vertical justification, line spacing and offset have been retained, whereas new attributes like color and opacity have been introduced.

We tried to make sure that you can use a vtkTextProperty to modify text properties in the same way a vtkProperty can be used to modify the surface properties of a geometric object. In that regard, you should be able to share a vtkTextProperty between different actors or assign the same vtkTextProperty to an actor that offers multiple vtkTextProperty attributes (vtkXYPlot for example).

Here is a quick example:

vtkTextActor *actor0 = vtkTextActor::New();
actor0->GetTextProperty()->SetItalic(1);
                                                    //
vtkTextProperty *tprop = vtkTextProperty::New();
tprop->SetBold(1);
                                                    //
vtkTextActor *actor1 = vtkTextActor::New();
actor1->SetTextProperty(tprop);
                                                    //
vtkTextActor *actor2 = vtkTextActor::New();
actor2->SetTextProperty(tprop);

• Backward compatibility issues*:

1) Color and Opacity:

The text color and text opacity settings are now controlled by the vtkTextProperty Color and Opacity attributes instead of the corresponding actor's color and opacity attributes. In the following example, those settings were controlled by the attributes of the vtkProperty2D attached to the vtkActor2D (vtkTextActor). The vtkTextProperty attributes should be used instead:

vtkTextActor *actor = vtkActor::New();
actor->GetProperty()->SetColor(...);
actor->GetProperty()->SetOpacity(...);

becomes:

actor->GetTextProperty()->SetColor(...);
actor->GetTextProperty()->SetOpacity(...);

To make migration easier for a while, we have set the vtkTextProperty default color to (-1.0, -1.0, -1.0) and the default opacity to -1.0. These "magic" values are checked by the underlying text mappers at rendering time. If they are found, the color and opacity of the 2D actor's vtkProperty2D are used, just as it was in VTK 4.1.

2) API (i.e. SetBold(), SetItalic(), etc)

Most of the VTK classes involving text used to provide their own text attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those classes would duplicate the vtkTextMapper API through methods like SetItalic(), SetBold(), SetFontFamily(), etc.

Moreover, if one class had different text elements (say, for example, the title and the labels of a scalar bar), there was no way to modify the text properties of these elements separately.

The vtkTextProperty class has been created to address both issues, by obsoleting those duplicated attributes and methods and providing a unified way to access text properties, and by allowing each class to associate different vtkTextProperty to different text elements.

Migrating your code basically involves using the old API on your actor's vtkTextProperty instead of the actor itself. For example:

actor->SetBold(1);

becomes:

actor->GetTextProperty()->SetBold(1);

When a class provides different vtkTextProperty for different text elements, the TextProperty attribute is usually prefixed with that element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty. This allows you to set different aspect for each text elements. If you want to use the same properties, you can either set the same values on each vtkTextProperty, or make both vtkTextProperty point to the same vtkTextProperty object. Example:

actor->GetAxisLabelTextProperty()->SetBold(1);
actor->GetAxisTitleTextProperty()->SetBold(1);

or:

vtkTextProperty *tprop = vtkTextProperty::New();
tprop->SetBold(1);
actor->SetAxisLabelTextProperty(tprop);
actor->SetAxisTitleTextProperty(tprop);

or:

actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());
actor->GetAxisTitleTextProperty()->SetBold(1);

The following list specifies the name of the text properties used in the VTK classes involving text.

vtkTextMapper:

• you can still use the vtkTextMapper + vtkActor2D combination, but we would advise you to use a single vtkTextActor instead, this will give you maximum flexibility.
• has 1 text prop: TextProperty, but although you have access to it, do not twwak it unless you are using vtkTextMapper with a vtkActor2D. In all other cases, use the text prop provided by the actor (see below).

vtkTextActor:

• has 1 text prop: TextProperty.

vtkLabeledDataMapper:

• has 1 text prop: LabelTextProperty.

vtkCaptionActor2D:

• has 1 text prop: CaptionTextProperty.

vtkLegendBoxActor:

• has 1 text prop: EntryTextProperty.

vtkAxisActor2D, vtkParallelCoordinatesActor, and vtkScalarBarActor:

• have 2 text props: TitleTextProperty, LabelTextProperty.

vtkXYPlotActor:

• has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)
• the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()
• the X (or Y) axis text props (i.e. title and label text props) can be retrieved through actor->GetX/YAxisActor2D->GetTitle/LabelTextProperty(), and will override the corresponding AxisTitleTextProperty or AxisLabelTextProperty props as long as they remain untouched.

vtkCubeAxesActor2D:

• has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)
• the X (Y or Z) axis text props (i.e. title and label text props) can be retrieved through actor->GetX/Y/ZAxisActor2D->GetTitle/LabelTextProperty(), and will override the corresponding AxisTitleTextProperty or AxisLabelTextProperty props as long as they remain untouched.

Forward declaration in VTK 4.x

Since VTK 4.x all classes have been carefully inspected to only include the necessesary headers, and do what is called 'forward declaration' for all other needed classes. Thus, when you compile your projects using a filter that takes as input a dataset and you are passing an imagedata: you need to explicitely include imagedata within your implementation file. This is true for all data types.

For example, if you get this error:

no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)

This means you need to add in your code : #include "vtkImageData.h"

Miscellaneous questions

What are the legal issues?

The Visualization Toolkit software is provided under the following copyright. We think it's pretty reasonable. We do restrict the distribution of modified code. This is primarily a revision control issue. We don't want a bunch of renegade vtks running around without us having some idea why the changes were made and giving us a chance to incorporate them into the general release.

Copyright © 1993-2004 Ken Martin, Will Schroeder, Bill Lorensen All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither name of Ken Martin, Will Schroeder, or Bill Lorensen nor the names of any contributors may be used to endorse or promote products derived from this software without specific prior written permission.

• Modified source versions must be plainly marked as such, and must not be misrepresented as being the original software.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Can't you split up the data file?

The data is now in one file that is about 15 Megabytes. This is smaller than the original data files VTK used and we hope that this size is not a problem for people anymore. If it is please let us know.

Do you have any shared library tips?

VTK version 4.0 and later supports both shared and static libraries on most all platforms. For development we typically use shared libraries since they are faster to link when making small changes. You can control how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.

What is the deal with the patents

As the copyright mentions there are some patents used in VTK. If you use any code in the Patented/ directory for commercial application you should contact the patent holder and obtain a license.

As of VTK4.0 the following classes are known to use algorithms patented by General Electric Company: vtkDecimate, vtkMarchingCubes, vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface. The GE contact is:

       Carl B. Horton
       Sr. Counsel, Intellectual Property
       3000 N. Grandview Blvd., W-710
       Waukesha, WI  53188
       Phone:  (262) 513-4022
       E-Mail: mailto:Carl.Horton@med.ge.com

As of VTK4.0 the following classes are known to use algorithms patented by Kitware, Inc.: vtkGridSynchronizedTemplates3D, vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and vtkSynchronizedTemplates3D. The Kitware contact is:

       Ken Martin
       Kitware
       469 Clifton Corporate Parkway,
       Clifton Park, NY 12065
       Phone:1-518-371-3971
       E-Mail: mailto:kitware@kitware.com