https://public.kitware.com/Wiki/api.php?action=feedcontributions&user=Seanmcbride&feedformat=atomKitwarePublic - User contributions [en]2024-03-29T04:39:52ZUser contributionsMediaWiki 1.38.6https://public.kitware.com/Wiki/index.php?title=Cocoa_VTK&diff=58088Cocoa VTK2015-07-27T19:04:09Z<p>Seanmcbride: /* VTK_USE_SYSTEM options */</p>
<hr />
<div>As VTK is cross-platform, building on Mac OS X is much the same as on any other supported platform. This page only discusses some OS X-specific topics related to VTK 5.10 and later. For information on antique versions of VTK, refer to the version of this page in the history from 2013-07-21 or earlier.<br />
<br />
== '''Supported Versions''' ==<br />
VTK 6.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.5 or later.<br />
<br />
VTK 5.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.4 or later.<br />
<br />
On OS X 10.5, you should use at least VTK 5.4.2. On OS X 10.6, at least VTK 5.6. On OS X 10.7 and later, VTK 6.x is recommended.<br />
<br />
== '''Windowing API''' ==<br />
<br />
On OS X, there are two windowing APIs: Carbon and Cocoa. Older versions of VTK defaulted to Carbon, but newer versions default to Cocoa. Carbon support is deprecated by both Apple and VTK, and should not be used for new development. To choose, set one of the following to ON:<br />
<br />
VTK_USE_CARBON:BOOL=ON<br />
VTK_USE_COCOA:BOOL=ON<br />
<br />
== '''Deployment Target and SDK''' ==<br />
<br />
The 'deployment target' and 'SDK' are concepts that should be familiar to OS X developers. In brief, the 'deployment target' specifies the oldest version of OS X that you which to support at runtime; it should always be set. Ex:<br />
<br />
CMAKE_OSX_DEPLOYMENT_TARGET:STRING=10.7<br />
<br />
The 'SDK' specifies which version of OS headers and libraries you want to build against. Usually, you want to built against the newest SDK, which is what CMake defaults to. But you can override it:<br />
<br />
CMAKE_OSX_SYSROOT:STRING=/path/to/SDK<br />
<br />
== '''Universal Binaries''' ==<br />
<br />
VTK can be built as a universal binary, that is, as libraries that have executable code for several CPU types. Even if you want to build for only one CPU type, you should always specify them explicitly, ex:<br />
<br />
CMAKE_OSX_ARCHITECTURES:STRING=i386;x86_64<br />
<br />
Possible values are: ppc, ppc64, i386, and x86_64.<br />
<br />
== '''Cocoa Memory Management Models''' ==<br />
<br />
Cocoa has three memory management models, chronologically by date of introduction:<br />
<br />
* manual reference counting (MRC)<br />
* garbage collection (GC)<br />
* automatic reference counting (ARC)<br />
<br />
VTK supports MRC and GC. MRC is the default. GC was deprecated by Apple in OS X 10.8, but to use it set:<br />
<br />
VTK_REQUIRED_OBJCXX_FLAGS:STRING=-fobjc-gc<br />
<br />
ARC support will eventually be available, but if your host application is ARC you can build VTK as MRC and still link to it.<br />
<br />
== '''VTK_USE_SYSTEM options''' ==<br />
<br />
VTK has several VTK_USE_SYSTEM_* options, allowing you to link against the OS's built-in versions of popular third party libraries. The advantage of doing so is that it reduces your compile time and binary size. Only a few are built-in to OS X, which you can make VTK use by setting:<br />
<br />
VTK_USE_SYSTEM_ZLIB:BOOL=ON<br />
VTK_USE_SYSTEM_EXPAT=ON<br />
VTK_USE_SYSTEM_LIBXML2=ON<br />
<br />
== '''Use Application Bundles''' ==<br />
<br />
On OS X, there are (at least) two kinds of executables:<br />
* Application Bundles<br />
* plain UNIX executables<br />
To be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction), OS X requires you to use an application bundle. If a plain UNIX executable tries, it will mostly work, but there will be various bugs, such as keyboard and mouse events not working properly.<br />
Many, but not all, of the VTK examples are built as plain UNIX executables, and thus have these problems. This is [http://vtk.org/Bug/view.php?id=2025 bug 2025].<br />
When you build your own VTK application, it is best to make it in the form of an application bundle. Simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an application bundle, see [http://vtk.org/Bug/view.php?id=2025 bug 2025] for possible workarounds.<br />
<br />
== '''SimpleCocoaVTK''' ==<br />
<br />
SimpleCocoaVTK is a sample Cocoa application written by Sean McBride and Mike Jackson that uses VTK. It illustrates how to use the VTK libraries within an Xcode-based OS X application. SimpleCocoaVTK is an example, it is not required to use VTK.<br />
<br />
Originally standalone, SimpleCocoaVTK is now part of VTK itself in the [http://vtk.org/gitweb?p=VTK.git;a=tree;f=Examples/GUI/Cocoa Examples/GUI/Cocoa] folder. See the documentation there for how to use it.<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=Cocoa_VTK&diff=58087Cocoa VTK2015-07-27T19:03:07Z<p>Seanmcbride: /* Cocoa Memory Management Models */</p>
<hr />
<div>As VTK is cross-platform, building on Mac OS X is much the same as on any other supported platform. This page only discusses some OS X-specific topics related to VTK 5.10 and later. For information on antique versions of VTK, refer to the version of this page in the history from 2013-07-21 or earlier.<br />
<br />
== '''Supported Versions''' ==<br />
VTK 6.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.5 or later.<br />
<br />
VTK 5.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.4 or later.<br />
<br />
On OS X 10.5, you should use at least VTK 5.4.2. On OS X 10.6, at least VTK 5.6. On OS X 10.7 and later, VTK 6.x is recommended.<br />
<br />
== '''Windowing API''' ==<br />
<br />
On OS X, there are two windowing APIs: Carbon and Cocoa. Older versions of VTK defaulted to Carbon, but newer versions default to Cocoa. Carbon support is deprecated by both Apple and VTK, and should not be used for new development. To choose, set one of the following to ON:<br />
<br />
VTK_USE_CARBON:BOOL=ON<br />
VTK_USE_COCOA:BOOL=ON<br />
<br />
== '''Deployment Target and SDK''' ==<br />
<br />
The 'deployment target' and 'SDK' are concepts that should be familiar to OS X developers. In brief, the 'deployment target' specifies the oldest version of OS X that you which to support at runtime; it should always be set. Ex:<br />
<br />
CMAKE_OSX_DEPLOYMENT_TARGET:STRING=10.7<br />
<br />
The 'SDK' specifies which version of OS headers and libraries you want to build against. Usually, you want to built against the newest SDK, which is what CMake defaults to. But you can override it:<br />
<br />
CMAKE_OSX_SYSROOT:STRING=/path/to/SDK<br />
<br />
== '''Universal Binaries''' ==<br />
<br />
VTK can be built as a universal binary, that is, as libraries that have executable code for several CPU types. Even if you want to build for only one CPU type, you should always specify them explicitly, ex:<br />
<br />
CMAKE_OSX_ARCHITECTURES:STRING=i386;x86_64<br />
<br />
Possible values are: ppc, ppc64, i386, and x86_64.<br />
<br />
== '''Cocoa Memory Management Models''' ==<br />
<br />
Cocoa has three memory management models, chronologically by date of introduction:<br />
<br />
* manual reference counting (MRC)<br />
* garbage collection (GC)<br />
* automatic reference counting (ARC)<br />
<br />
VTK supports MRC and GC. MRC is the default. GC was deprecated by Apple in OS X 10.8, but to use it set:<br />
<br />
VTK_REQUIRED_OBJCXX_FLAGS:STRING=-fobjc-gc<br />
<br />
ARC support will eventually be available, but if your host application is ARC you can build VTK as MRC and still link to it.<br />
<br />
== '''VTK_USE_SYSTEM options''' ==<br />
<br />
VTK has several VTK_USE_SYSTEM_* options, allowing you to link against the OS's built-in versions of popular third party libraries. The advantage in doing so is that it reduces your compile time and binary size. On OS X, only a few are included, which you can make VTK use by setting:<br />
<br />
VTK_USE_SYSTEM_ZLIB:BOOL=ON<br />
VTK_USE_SYSTEM_EXPAT=ON<br />
VTK_USE_SYSTEM_LIBXML2=ON<br />
<br />
== '''Use Application Bundles''' ==<br />
<br />
On OS X, there are (at least) two kinds of executables:<br />
* Application Bundles<br />
* plain UNIX executables<br />
To be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction), OS X requires you to use an application bundle. If a plain UNIX executable tries, it will mostly work, but there will be various bugs, such as keyboard and mouse events not working properly.<br />
Many, but not all, of the VTK examples are built as plain UNIX executables, and thus have these problems. This is [http://vtk.org/Bug/view.php?id=2025 bug 2025].<br />
When you build your own VTK application, it is best to make it in the form of an application bundle. Simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an application bundle, see [http://vtk.org/Bug/view.php?id=2025 bug 2025] for possible workarounds.<br />
<br />
== '''SimpleCocoaVTK''' ==<br />
<br />
SimpleCocoaVTK is a sample Cocoa application written by Sean McBride and Mike Jackson that uses VTK. It illustrates how to use the VTK libraries within an Xcode-based OS X application. SimpleCocoaVTK is an example, it is not required to use VTK.<br />
<br />
Originally standalone, SimpleCocoaVTK is now part of VTK itself in the [http://vtk.org/gitweb?p=VTK.git;a=tree;f=Examples/GUI/Cocoa Examples/GUI/Cocoa] folder. See the documentation there for how to use it.<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=Cocoa_VTK&diff=58086Cocoa VTK2015-07-27T18:59:58Z<p>Seanmcbride: /* Supported Versions */</p>
<hr />
<div>As VTK is cross-platform, building on Mac OS X is much the same as on any other supported platform. This page only discusses some OS X-specific topics related to VTK 5.10 and later. For information on antique versions of VTK, refer to the version of this page in the history from 2013-07-21 or earlier.<br />
<br />
== '''Supported Versions''' ==<br />
VTK 6.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.5 or later.<br />
<br />
VTK 5.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.4 or later.<br />
<br />
On OS X 10.5, you should use at least VTK 5.4.2. On OS X 10.6, at least VTK 5.6. On OS X 10.7 and later, VTK 6.x is recommended.<br />
<br />
== '''Windowing API''' ==<br />
<br />
On OS X, there are two windowing APIs: Carbon and Cocoa. Older versions of VTK defaulted to Carbon, but newer versions default to Cocoa. Carbon support is deprecated by both Apple and VTK, and should not be used for new development. To choose, set one of the following to ON:<br />
<br />
VTK_USE_CARBON:BOOL=ON<br />
VTK_USE_COCOA:BOOL=ON<br />
<br />
== '''Deployment Target and SDK''' ==<br />
<br />
The 'deployment target' and 'SDK' are concepts that should be familiar to OS X developers. In brief, the 'deployment target' specifies the oldest version of OS X that you which to support at runtime; it should always be set. Ex:<br />
<br />
CMAKE_OSX_DEPLOYMENT_TARGET:STRING=10.7<br />
<br />
The 'SDK' specifies which version of OS headers and libraries you want to build against. Usually, you want to built against the newest SDK, which is what CMake defaults to. But you can override it:<br />
<br />
CMAKE_OSX_SYSROOT:STRING=/path/to/SDK<br />
<br />
== '''Universal Binaries''' ==<br />
<br />
VTK can be built as a universal binary, that is, as libraries that have executable code for several CPU types. Even if you want to build for only one CPU type, you should always specify them explicitly, ex:<br />
<br />
CMAKE_OSX_ARCHITECTURES:STRING=i386;x86_64<br />
<br />
Possible values are: ppc, ppc64, i386, and x86_64.<br />
<br />
== '''Cocoa Memory Management Models''' ==<br />
<br />
Cocoa has three memory management models, chronologically by date of introduction:<br />
<br />
* manual reference counting (MRC)<br />
* garbage collection (GC)<br />
* automatic reference counting (ARC)<br />
<br />
VTK supports MRC and GC. ARC support will eventually be available in VTK 6.x.<br />
<br />
MRC is the default. GC was deprecated in OS X 10.8, but to use it set:<br />
<br />
VTK_REQUIRED_OBJCXX_FLAGS:STRING=-fobjc-gc<br />
<br />
== '''VTK_USE_SYSTEM options''' ==<br />
<br />
VTK has several VTK_USE_SYSTEM_* options, allowing you to link against the OS's built-in versions of popular third party libraries. The advantage in doing so is that it reduces your compile time and binary size. On OS X, only a few are included, which you can make VTK use by setting:<br />
<br />
VTK_USE_SYSTEM_ZLIB:BOOL=ON<br />
VTK_USE_SYSTEM_EXPAT=ON<br />
VTK_USE_SYSTEM_LIBXML2=ON<br />
<br />
== '''Use Application Bundles''' ==<br />
<br />
On OS X, there are (at least) two kinds of executables:<br />
* Application Bundles<br />
* plain UNIX executables<br />
To be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction), OS X requires you to use an application bundle. If a plain UNIX executable tries, it will mostly work, but there will be various bugs, such as keyboard and mouse events not working properly.<br />
Many, but not all, of the VTK examples are built as plain UNIX executables, and thus have these problems. This is [http://vtk.org/Bug/view.php?id=2025 bug 2025].<br />
When you build your own VTK application, it is best to make it in the form of an application bundle. Simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an application bundle, see [http://vtk.org/Bug/view.php?id=2025 bug 2025] for possible workarounds.<br />
<br />
== '''SimpleCocoaVTK''' ==<br />
<br />
SimpleCocoaVTK is a sample Cocoa application written by Sean McBride and Mike Jackson that uses VTK. It illustrates how to use the VTK libraries within an Xcode-based OS X application. SimpleCocoaVTK is an example, it is not required to use VTK.<br />
<br />
Originally standalone, SimpleCocoaVTK is now part of VTK itself in the [http://vtk.org/gitweb?p=VTK.git;a=tree;f=Examples/GUI/Cocoa Examples/GUI/Cocoa] folder. See the documentation there for how to use it.<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=Cocoa_VTK&diff=58085Cocoa VTK2015-07-27T18:59:28Z<p>Seanmcbride: /* Supported Versions */</p>
<hr />
<div>As VTK is cross-platform, building on Mac OS X is much the same as on any other supported platform. This page only discusses some OS X-specific topics related to VTK 5.10 and later. For information on antique versions of VTK, refer to the version of this page in the history from 2013-07-21 or earlier.<br />
<br />
== '''Supported Versions''' ==<br />
VTK 6.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.5 or later.<br />
<br />
VTK 5.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.4 or later.<br />
<br />
On OS X 10.5, you should use at least VTK 5.4.2. On OS X 10.6, at least VTK 5.6. On OS X 10.7 and later, VTK 6 is recommended.<br />
<br />
== '''Windowing API''' ==<br />
<br />
On OS X, there are two windowing APIs: Carbon and Cocoa. Older versions of VTK defaulted to Carbon, but newer versions default to Cocoa. Carbon support is deprecated by both Apple and VTK, and should not be used for new development. To choose, set one of the following to ON:<br />
<br />
VTK_USE_CARBON:BOOL=ON<br />
VTK_USE_COCOA:BOOL=ON<br />
<br />
== '''Deployment Target and SDK''' ==<br />
<br />
The 'deployment target' and 'SDK' are concepts that should be familiar to OS X developers. In brief, the 'deployment target' specifies the oldest version of OS X that you which to support at runtime; it should always be set. Ex:<br />
<br />
CMAKE_OSX_DEPLOYMENT_TARGET:STRING=10.7<br />
<br />
The 'SDK' specifies which version of OS headers and libraries you want to build against. Usually, you want to built against the newest SDK, which is what CMake defaults to. But you can override it:<br />
<br />
CMAKE_OSX_SYSROOT:STRING=/path/to/SDK<br />
<br />
== '''Universal Binaries''' ==<br />
<br />
VTK can be built as a universal binary, that is, as libraries that have executable code for several CPU types. Even if you want to build for only one CPU type, you should always specify them explicitly, ex:<br />
<br />
CMAKE_OSX_ARCHITECTURES:STRING=i386;x86_64<br />
<br />
Possible values are: ppc, ppc64, i386, and x86_64.<br />
<br />
== '''Cocoa Memory Management Models''' ==<br />
<br />
Cocoa has three memory management models, chronologically by date of introduction:<br />
<br />
* manual reference counting (MRC)<br />
* garbage collection (GC)<br />
* automatic reference counting (ARC)<br />
<br />
VTK supports MRC and GC. ARC support will eventually be available in VTK 6.x.<br />
<br />
MRC is the default. GC was deprecated in OS X 10.8, but to use it set:<br />
<br />
VTK_REQUIRED_OBJCXX_FLAGS:STRING=-fobjc-gc<br />
<br />
== '''VTK_USE_SYSTEM options''' ==<br />
<br />
VTK has several VTK_USE_SYSTEM_* options, allowing you to link against the OS's built-in versions of popular third party libraries. The advantage in doing so is that it reduces your compile time and binary size. On OS X, only a few are included, which you can make VTK use by setting:<br />
<br />
VTK_USE_SYSTEM_ZLIB:BOOL=ON<br />
VTK_USE_SYSTEM_EXPAT=ON<br />
VTK_USE_SYSTEM_LIBXML2=ON<br />
<br />
== '''Use Application Bundles''' ==<br />
<br />
On OS X, there are (at least) two kinds of executables:<br />
* Application Bundles<br />
* plain UNIX executables<br />
To be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction), OS X requires you to use an application bundle. If a plain UNIX executable tries, it will mostly work, but there will be various bugs, such as keyboard and mouse events not working properly.<br />
Many, but not all, of the VTK examples are built as plain UNIX executables, and thus have these problems. This is [http://vtk.org/Bug/view.php?id=2025 bug 2025].<br />
When you build your own VTK application, it is best to make it in the form of an application bundle. Simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an application bundle, see [http://vtk.org/Bug/view.php?id=2025 bug 2025] for possible workarounds.<br />
<br />
== '''SimpleCocoaVTK''' ==<br />
<br />
SimpleCocoaVTK is a sample Cocoa application written by Sean McBride and Mike Jackson that uses VTK. It illustrates how to use the VTK libraries within an Xcode-based OS X application. SimpleCocoaVTK is an example, it is not required to use VTK.<br />
<br />
Originally standalone, SimpleCocoaVTK is now part of VTK itself in the [http://vtk.org/gitweb?p=VTK.git;a=tree;f=Examples/GUI/Cocoa Examples/GUI/Cocoa] folder. See the documentation there for how to use it.<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=Cocoa_VTK&diff=58084Cocoa VTK2015-07-27T16:42:20Z<p>Seanmcbride: /* VTK_USE_SYSTEM options */</p>
<hr />
<div>As VTK is cross-platform, building on Mac OS X is much the same as on any other supported platform. This page only discusses some OS X-specific topics related to VTK 5.10 and later. For information on antique versions of VTK, refer to the version of this page in the history from 2013-07-21 or earlier.<br />
<br />
== '''Supported Versions''' ==<br />
VTK 6.0 supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.5 or later.<br />
<br />
VTK 5.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.4 or later.<br />
<br />
On OS X 10.5, you should use at least VTK 5.4.2. On OS X 10.6, at least VTK 5.6. On OS X 10.7 and later, VTK 6 is recommended.<br />
<br />
== '''Windowing API''' ==<br />
<br />
On OS X, there are two windowing APIs: Carbon and Cocoa. Older versions of VTK defaulted to Carbon, but newer versions default to Cocoa. Carbon support is deprecated by both Apple and VTK, and should not be used for new development. To choose, set one of the following to ON:<br />
<br />
VTK_USE_CARBON:BOOL=ON<br />
VTK_USE_COCOA:BOOL=ON<br />
<br />
== '''Deployment Target and SDK''' ==<br />
<br />
The 'deployment target' and 'SDK' are concepts that should be familiar to OS X developers. In brief, the 'deployment target' specifies the oldest version of OS X that you which to support at runtime; it should always be set. Ex:<br />
<br />
CMAKE_OSX_DEPLOYMENT_TARGET:STRING=10.7<br />
<br />
The 'SDK' specifies which version of OS headers and libraries you want to build against. Usually, you want to built against the newest SDK, which is what CMake defaults to. But you can override it:<br />
<br />
CMAKE_OSX_SYSROOT:STRING=/path/to/SDK<br />
<br />
== '''Universal Binaries''' ==<br />
<br />
VTK can be built as a universal binary, that is, as libraries that have executable code for several CPU types. Even if you want to build for only one CPU type, you should always specify them explicitly, ex:<br />
<br />
CMAKE_OSX_ARCHITECTURES:STRING=i386;x86_64<br />
<br />
Possible values are: ppc, ppc64, i386, and x86_64.<br />
<br />
== '''Cocoa Memory Management Models''' ==<br />
<br />
Cocoa has three memory management models, chronologically by date of introduction:<br />
<br />
* manual reference counting (MRC)<br />
* garbage collection (GC)<br />
* automatic reference counting (ARC)<br />
<br />
VTK supports MRC and GC. ARC support will eventually be available in VTK 6.x.<br />
<br />
MRC is the default. GC was deprecated in OS X 10.8, but to use it set:<br />
<br />
VTK_REQUIRED_OBJCXX_FLAGS:STRING=-fobjc-gc<br />
<br />
== '''VTK_USE_SYSTEM options''' ==<br />
<br />
VTK has several VTK_USE_SYSTEM_* options, allowing you to link against the OS's built-in versions of popular third party libraries. The advantage in doing so is that it reduces your compile time and binary size. On OS X, only a few are included, which you can make VTK use by setting:<br />
<br />
VTK_USE_SYSTEM_ZLIB:BOOL=ON<br />
VTK_USE_SYSTEM_EXPAT=ON<br />
VTK_USE_SYSTEM_LIBXML2=ON<br />
<br />
== '''Use Application Bundles''' ==<br />
<br />
On OS X, there are (at least) two kinds of executables:<br />
* Application Bundles<br />
* plain UNIX executables<br />
To be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction), OS X requires you to use an application bundle. If a plain UNIX executable tries, it will mostly work, but there will be various bugs, such as keyboard and mouse events not working properly.<br />
Many, but not all, of the VTK examples are built as plain UNIX executables, and thus have these problems. This is [http://vtk.org/Bug/view.php?id=2025 bug 2025].<br />
When you build your own VTK application, it is best to make it in the form of an application bundle. Simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an application bundle, see [http://vtk.org/Bug/view.php?id=2025 bug 2025] for possible workarounds.<br />
<br />
== '''SimpleCocoaVTK''' ==<br />
<br />
SimpleCocoaVTK is a sample Cocoa application written by Sean McBride and Mike Jackson that uses VTK. It illustrates how to use the VTK libraries within an Xcode-based OS X application. SimpleCocoaVTK is an example, it is not required to use VTK.<br />
<br />
Originally standalone, SimpleCocoaVTK is now part of VTK itself in the [http://vtk.org/gitweb?p=VTK.git;a=tree;f=Examples/GUI/Cocoa Examples/GUI/Cocoa] folder. See the documentation there for how to use it.<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK&diff=55195VTK2014-03-10T15:00:29Z<p>Seanmcbride: Note removal of -fobjc-gc under Cocoa</p>
<hr />
<div><center>http://public.kitware.com/images/logos/vtk-logo2.jpg</center><br />
<br /><br />
The Visualization ToolKit (VTK) is an open source, freely available software system for 3D computer graphics, image processing, and visualization used by thousands of researchers and developers around the world. VTK consists of a C++ class library, and several interpreted interface layers including Python, Tcl/Tk and Java. Professional support and products for VTK are provided by Kitware, Inc. ([http://www.kitware.com www.kitware.com]) VTK supports a wide variety of visualization algorithms including scalar, vector, tensor, texture, and volumetric methods; and advanced modeling techniques such as implicit modelling, 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.<br />
<br />
<br />
== Learning VTK ==<br />
If you want to learn how to use or develop VTK, please see [[VTK/Learning_VTK | Learning VTK]]<br />
<br />
== Building VTK ==<br />
* Where can I [http://vtk.org/get-software.php download VTK]?<br />
<br />
* Where can I download a tarball of the [http://vtk.org/files/nightly/vtkNightlyDocHtml.tar.gz nightly HTML documentation]?<br />
<br />
* How do I build the [[VTK/BuildingDoxygen|Doxygen documentation]]?<br />
<br />
* [[VTK/Git|Using Git for VTK development]]<br />
<br />
* [[VTK/GitMSBuild|Using Git and MSBuild to build VTK]]<br />
<br />
* [[VTK/PythonDevelopment|Setting up a Python Development Environment using Eclipse/Pydev]]<br />
<br />
* [[VTK/Build parameters | Build parameters]]<br />
<br />
* [[Making Development Environment without compiling source distribution]]<br />
<br />
* [[VTK/Building/VisualStudio | Building VTK with Visual Studio]]<br />
<br />
== Extending VTK ==<br />
<br />
* Where can I get [[VTK Datasets]]?<br />
<br />
* [[VTK Classes|User-Contributed Classes]]<br />
<br />
* [[VTK Coding Standards]] <br />
<br />
* [[VTK/Commit_Guidelines|VTK Commit Guidelines]]<br />
<br />
* [[VTK/Git/Develop|Contribute to VTK / Patch Procedure]]<br />
<br />
* [[VTK Scripts|Extending VTK with Scripts]]<br />
<br />
== Projects/ Tools that use VTK == <br />
<br />
* [[VTK Tools|VTK-Based Tools and Applications]]<br />
<br />
* What are some [[VTK Projects|projects using VTK]]?<br />
<br />
== Troubleshooting ==<br />
* [[VTK FAQ|Frequently asked questions (FAQ)]]<br />
<br />
== Miscellaneous ==<br />
* [[VTK Related Job Opportunities|VTK Related Job Opportunities]]<br />
<br />
* [[VTK/Third Party Library Patrol | VTK 3rd Party Library Patrol]]<br />
<br />
* [[VTK/Meeting Minutes | Meeting Minutes]]<br />
<br />
* [[VTK/License | VTK License]]<br />
* [[VTK/ThirdPartyLicenses | VTK Third-Party Licenses]]<br />
<br />
== Summary of Changes ==<br />
<br />
==== VTK 6.2 (git master) ====<br />
<br />
* Under Cocoa, removed "-fobjc-gc" as a default compiler flag. VTK still supports Cocoa garbage collection, but you must specify it yourself now.<br />
<br />
==== VTK 6.1 ====<br />
<br />
* Move to use CMake's external data support over VTKData<br />
* [[VTK/OpenGL_Errors | OpenGL error detection and reporting macros and error cleanup ]]<br />
* [[VTK/OpenGL_Driver_Information | API for dealing with OpenGL driver bugs ]]<br />
* [[VTK/OSMesa_Support | Enable rendering with OSMesa where possible ]]<br />
* [[ParaView/Line_Integral_Convolution | Surface LIC parallelization and features for interactive tuning ]]<br />
* [[VTK/VTK_SMP | SMP framework introduced to make shared memory parallel development]]<br />
* Fixed compiler/linker errors when building against OS X 10.9 SDK. Fixed other errors building against llvm's [http://libcxx.llvm.org libc++].<br />
* Support for unicode text when a suitable font file is used in vtkTextProperty.<br />
* [[VTK/Wrapping C++11 Code | Wrapper support for header files with C++11 syntax]].<br />
* [[VTK/Better_Java_Support | Better Java support and install rules]]<br />
* Depth peeling support for ATI devices<br />
* Ctests generate a stacktrace on POSIX systems in response to catastrophic failure such as abort or segfault.<br />
* [[VTK/API_Changes_6_0_0_to_6_1_0 | API Diff Report]]<br />
<br />
==== VTK 6.0 ====<br />
<br />
* [[VTK/VTK_6_Migration_Guide | VTK 6 API Migration Guide]]<br />
* [[VTK/Build_System_Migration | VTK 6 (build system) Migration Guide]]<br />
* [[VTK/Module_Development | VTK 6 Module Development]]<br />
* [[VTK/Remove_VTK_4_Compatibility | Remove VTK 4 compatibility layer from pipeline]]<br />
* [[VTK/Modularization_Proposal | Modularization]]<br />
* [[VTK/Remove_vtkTemporalDataSet | Temporal support changes]]<br />
* [[VTK/Composite_data_changes | Composite data structure changes ]]<br />
* [[VTK/API_Changes_5_10_1_to_6_0_0 | API Diff Report]]<br />
<br />
==== VTK 5.10 ====<br />
<br />
* [[VTK/improved unicode support | Change unicode readers/writers to register as codecs (finished Oct 29 2010)]]<br />
* [[VTK/Image Rendering Classes | New image rendering classes (start Dec 15 2010, finish Mar 15 2011)]]<br />
* [[VTK/Image Interpolators | Image interpolators (start Jun 20 2011, finish Aug 31 2011)]]<br />
* [[VTK/GSoC | Projects from Google Summer of Code 2011]]<br />
* [[VTK/Release5100 New Classes | List of new classes in 5.10]]<br />
* [[VTK/API_Changes_5_8_0_to_6_1_0 | API Diff Report]]<br />
<br />
==== VTK 5.8 ====<br />
<br />
* [[VTK/Polyhedron_Support | Polyhedron cells and MVC Interpolation]]<br />
* [http://visimp.cs.unc.edu/2010/10/26/reeb-graphs/ Reeb Graphs]<br />
* [[VTK/Closed Surface Clipping | Clipping of closed surfaces (start Mar 26, 2010, finish Apr 22, 2010)]]<br />
* [[VTK/Wrapper Update 2010 | New wrappers (start Apr 28, 2010)]]<br />
* [[VTK/Image Stencil Improvements | Improved image stencil support (start Nov 3, 2010)]]<br />
* [[VTK/MNI File Formats | MNI file formats]]<br />
* [[VTK/Release580 New Classes | List of New Classes]]<br />
<br />
==== VTK 5.6 ====<br />
<br />
* [[VTK/MultiPass_Rendering | VTK Multi-Pass Rendering]]<br />
* [[VTK/Multicore and Streaming | Multicore and Streaming]]<br />
* [[VTK/statistics | Statistics]]<br />
* [[VTK/Array Refactoring | Array Refactoring]]<br />
* [[VTK/3DConnexion Devices Support | 3DConnexion Devices Support]]<br />
* [[VTK/Charts | New Charts API]]<br />
* [[VTK/New CellPicker | New Cell Picker and Volume Picking (start Nov 2010, finish Feb 2010)]]<br />
<br />
==== VTK 5.4 ====<br />
<br />
* [[VTK 5.4 Release Planning]]<br />
* [[VTK/Cray XT3 Compilation| Cray XT3 Compilation]]<br />
* [[VTK/Geovis vision toolkit | Geospatial and vision visualization support ]]<br />
<br />
==== VTK 5.2 ====<br />
<br />
* [[VTK/Java Wrapping | VTK Java Wrapping]]<br />
* [[VTK/Composite Data Redesign | Composite Data Redesign]]<br />
* [[VTK Shaders | VTK Shaders]]<br />
* [[VTKShaders | Shaders in VTK]]<br />
* [[VTK/VTKMatlab | VTK with Matlab]]<br />
* [[VTK/Time_Support | VTK Time support]]<br />
* [[VTK/Graph Layout | VTK Graph Layout]]<br />
* [[VTK/Depth_Peeling | VTK Depth Peeling]]<br />
* [[VTK/Using_JRuby | Using VTK with JRuby]]<br />
* [[VTK/Painters | Painters]]<br />
<br />
==== VTK 5.0 ====<br />
<br />
* [[VTK/Tutorials/New_Pipeline | New Pipeline]]<br />
* [[VTKWidgets | VTK Widget Redesign]]<br />
<br />
== News ==<br />
<br />
=== Development Process ===<br />
The VTK Community is [[VTK/Managing_the_Development_Process | upgrading its development process]]. The current process using Git can be found at the [[VTK/Git|VTK Git page]]. We are doing this in response to the continuing and rapid growth of the toolkit. A VTK Architecture Review Board [[VTK/Architecture_Review_Board |VTK ARB]] is being put in place to provide strategic guidance to the community, and individuals are being identified as leaders in various VTK subsystems.<br />
<br />
Have a question or topic for the ARB to discuss about the future of VTK? First, please bring the topic to the [http://public.kitware.com/mailman/listinfo/vtk-developers VTK developers mailing list]. If the issue is not resolved there or needs further planning or direction, you may [[VTK/ARB/Meetings#Potential Topics|enter a suggested topic for discussion]].<br />
<br />
* [[Proposed Changes to VTK | Proposed Changes to VTK]]<br />
<br />
===[[VTK/NextGen|VTK NextGen]]=== <br />
We have started collecting works in progress as well as future ideas at [[VTK/NextGen|NextGen]]. Please add anything you are working on, would like to collaborate on, or would like to see in the future of VTK!<br />
<br />
== Wrapping ==<br />
<br />
* [[VTK/Wrappers | Wrapping Tools]]<br />
<br />
* [[VTK/Java Wrapping|Java]]<br />
** [[VTK/Java Code Samples|Java code samples]]<br />
* [[VTK/Python Wrapping FAQ|Python]]<br />
** [[VTK/Python Wrapper Enhancement|Python wrapper enhancements]]<br />
* [[VTK/CSharp/ActiViz.NET|CSharp/ActiViz.NET]]<br />
** [[VTK/Examples/CSharp|CSharp/ActiViz.NET code samples]]<br />
* [[VTK/CSharp/ComingSoon|CSharp/ComingSoon]]<br />
<br />
== Developers Corner ==<br />
[[VTK/Git|Development process with Git]]<br />
<br />
[[VTK/Developers Corner|Developers Corner]]<br />
<br />
<!-- <br />
== External Links ==<br />
dead link *[http://zorayasantos.tripod.com/vtk_csharp_examples VTK examples in C#] (Visual Studio 5.0 and .NET 2.0)<br />
--><br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK&diff=54427VTK2013-11-04T16:37:16Z<p>Seanmcbride: /* VTK 6.1 */</p>
<hr />
<div><center>http://public.kitware.com/images/logos/vtk-logo2.jpg</center><br />
<br /><br />
The Visualization ToolKit (VTK) is an open source, freely available software system for 3D computer graphics, image processing, and visualization used by thousands of researchers and developers around the world. VTK consists of a C++ class library, and several interpreted interface layers including Python, Tcl/Tk and Java. Professional support and products for VTK are provided by Kitware, Inc. ([http://www.kitware.com www.kitware.com]) VTK supports a wide variety of visualization algorithms including scalar, vector, tensor, texture, and volumetric methods; and advanced modeling techniques such as implicit modelling, 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.<br />
<br />
<br />
== Learning VTK ==<br />
If you want to learn how to use or develop VTK, please see [[VTK/Learning_VTK | Learning VTK]]<br />
<br />
== Building VTK ==<br />
* Where can I [http://vtk.org/get-software.php download VTK]?<br />
<br />
* Where can I download a tarball of the [http://vtk.org/files/nightly/vtkNightlyDocHtml.tar.gz nightly HTML documentation]?<br />
<br />
* How do I build the [[VTK/BuildingDoxygen|Doxygen documentation]]?<br />
<br />
* [[VTK/Git|Using Git for VTK development]]<br />
<br />
* [[VTK/GitMSBuild|Using Git and MSBuild to build VTK]]<br />
<br />
* [[VTK/PythonDevelopment|Setting up a Python Development Environment using Eclipse/Pydev]]<br />
<br />
* [[VTK/Build parameters | Build parameters]]<br />
<br />
* [[Making Development Environment without compiling source distribution]]<br />
<br />
* [[VTK/Building/VisualStudio | Building VTK with Visual Studio]]<br />
<br />
== Extending VTK ==<br />
<br />
* Where can I get [[VTK Datasets]]?<br />
<br />
* [[VTK Classes|User-Contributed Classes]]<br />
<br />
* [[VTK Coding Standards]] <br />
<br />
* [[VTK/Commit_Guidelines|VTK Commit Guidelines]]<br />
<br />
* [[VTK/Git/Develop|Contribute to VTK / Patch Procedure]]<br />
<br />
* [[VTK Scripts|Extending VTK with Scripts]]<br />
<br />
== Projects/ Tools that use VTK == <br />
<br />
* [[VTK Tools|VTK-Based Tools and Applications]]<br />
<br />
* What are some [[VTK Projects|projects using VTK]]?<br />
<br />
== Troubleshooting ==<br />
<br />
* [[VTK FAQ|Frequently asked questions (FAQ)]]<br />
<br />
* [[VTK OpenGL|Common OpenGL troubles]]<br />
<br />
== Miscellaneous ==<br />
* [[VTK Related Job Opportunities|VTK Related Job Opportunities]]<br />
<br />
* [[VTK/Third Party Library Patrol | VTK 3rd Party Library Patrol]]<br />
<br />
* [[VTK/Meeting Minutes | Meeting Minutes]]<br />
<br />
* [[VTK/License | VTK License]]<br />
* [[VTK/ThirdPartyLicenses | VTK Third-Party Licenses]]<br />
<br />
== Summary of Changes ==<br />
<br />
==== VTK 6.1 ====<br />
<br />
* Move to use CMake's external data support over VTKData<br />
* [[VTK/OpenGL_Errors | OpenGL error detection and reporting ]]<br />
* [[VTK/VTK_SMP | SMP framework introduced to make shared memory parallel development]]<br />
* Fixed compiler/linker errors when building against OS X 10.9 SDK. Fixed other errors building against llvm's [http://libcxx.llvm.org libc++].<br />
<br />
==== VTK 6.0 ====<br />
<br />
* [[VTK/VTK_6_Migration_Guide | VTK 6 API Migration Guide]]<br />
* [[VTK/Build_System_Migration | VTK 6 (build system) Migration Guide]]<br />
* [[VTK/Module_Development | VTK 6 Module Development]]<br />
* [[VTK/Remove_VTK_4_Compatibility | Remove VTK 4 compatibility layer from pipeline]]<br />
* [[VTK/Modularization_Proposal | Modularization]]<br />
* [[VTK/Remove_vtkTemporalDataSet | Temporal support changes]]<br />
* [[VTK/Composite_data_changes | Composite data structure changes ]]<br />
<br />
==== VTK 5.10 ====<br />
<br />
* [[VTK/improved unicode support | Change unicode readers/writers to register as codecs (finished Oct 29 2010)]]<br />
* [[VTK/Image Rendering Classes | New image rendering classes (start Dec 15 2010, finish Mar 15 2011)]]<br />
* [[VTK/Image Interpolators | Image interpolators (start Jun 20 2011, finish Aug 31 2011)]]<br />
* [[VTK/GSoC | Projects from Google Summer of Code 2011]]<br />
* [[VTK/Release5100 New Classes | List of new classes in 5.10]]<br />
<br />
==== VTK 5.8 ====<br />
<br />
* [[VTK/Polyhedron_Support | Polyhedron cells and MVC Interpolation]]<br />
* [http://visimp.cs.unc.edu/2010/10/26/reeb-graphs/ Reeb Graphs]<br />
* [[VTK/Closed Surface Clipping | Clipping of closed surfaces (start Mar 26, 2010, finish Apr 22, 2010)]]<br />
* [[VTK/Wrapper Update 2010 | New wrappers (start Apr 28, 2010)]]<br />
* [[VTK/Image Stencil Improvements | Improved image stencil support (start Nov 3, 2010)]]<br />
* [[VTK/MNI File Formats | MNI file formats]]<br />
* [[VTK/Release580 New Classes | List of New Classes]]<br />
<br />
==== VTK 5.6 ====<br />
<br />
* [[VTK/MultiPass_Rendering | VTK Multi-Pass Rendering]]<br />
* [[VTK/Multicore and Streaming | Multicore and Streaming]]<br />
* [[VTK/statistics | Statistics]]<br />
* [[VTK/Array Refactoring | Array Refactoring]]<br />
* [[VTK/3DConnexion Devices Support | 3DConnexion Devices Support]]<br />
* [[VTK/Charts | New Charts API]]<br />
* [[VTK/New CellPicker | New Cell Picker and Volume Picking (start Nov 2010, finish Feb 2010)]]<br />
<br />
==== VTK 5.4 ====<br />
<br />
* [[VTK 5.4 Release Planning]]<br />
* [[VTK/Cray XT3 Compilation| Cray XT3 Compilation]]<br />
* [[VTK/Geovis vision toolkit | Geospatial and vision visualization support ]]<br />
<br />
==== VTK 5.2 ====<br />
<br />
* [[VTK/Java Wrapping | VTK Java Wrapping]]<br />
* [[VTK/Composite Data Redesign | Composite Data Redesign]]<br />
* [[VTK Shaders | VTK Shaders]]<br />
* [[VTKShaders | Shaders in VTK]]<br />
* [[VTK/VTKMatlab | VTK with Matlab]]<br />
* [[VTK/Time_Support | VTK Time support]]<br />
* [[VTK/Graph Layout | VTK Graph Layout]]<br />
* [[VTK/Depth_Peeling | VTK Depth Peeling]]<br />
* [[VTK/Using_JRuby | Using VTK with JRuby]]<br />
* [[VTK/Painters | Painters]]<br />
<br />
==== VTK 5.0 ====<br />
<br />
* [[VTK/Tutorials/New_Pipeline | New Pipeline]]<br />
* [[VTKWidgets | VTK Widget Redesign]]<br />
<br />
== News ==<br />
<br />
=== Development Process ===<br />
The VTK Community is [[VTK/Managing_the_Development_Process | upgrading its development process]]. We are doing this in response to the continuing and rapid growth of the toolkit. A VTK Architecture Review Board [[VTK/Architecture_Review_Board |VTK ARB]] is being put in place to provide strategic guidance to the community, and individuals are being identified as leaders in various VTK subsystems.<br />
<br />
Have a question or topic for the ARB to discuss about the future of VTK? First, please bring the topic to the [http://public.kitware.com/mailman/listinfo/vtk-developers VTK developers mailing list]. If the issue is not resolved there or needs further planning or direction, you may [[VTK/ARB/Meetings#Potential Topics|enter a suggested topic for discussion]].<br />
<br />
* [[Proposed Changes to VTK | Proposed Changes to VTK]]<br />
<br />
===[[VTK/NextGen|VTK NextGen]]=== <br />
We have started collecting works in progress as well as future ideas at [[VTK/NextGen|NextGen]]. Please add anything you are working on, would like to collaborate on, or would like to see in the future of VTK!<br />
<br />
== Wrapping ==<br />
<br />
* [[VTK/Wrappers | Wrapping Tools]]<br />
<br />
* [[VTK/Java Wrapping|Java]]<br />
** [[VTK/Java Code Samples|Java code samples]]<br />
* [[VTK/Python Wrapping FAQ|Python]]<br />
** [[VTK/Python Wrapper Enhancement|Python wrapper enhancements]]<br />
* [[VTK/CSharp/ActiViz.NET|CSharp/ActiViz.NET]]<br />
** [[VTK/Examples/CSharp|CSharp/ActiViz.NET code samples]]<br />
* [[VTK/CSharp/ComingSoon|CSharp/ComingSoon]]<br />
<br />
== Developers Corner ==<br />
[[VTK/Developers Corner|Developers Corner]]<br />
<br />
<!-- <br />
== External Links ==<br />
dead link *[http://zorayasantos.tripod.com/vtk_csharp_examples VTK examples in C#] (Visual Studio 5.0 and .NET 2.0)<br />
--><br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=53354VTK/FAQ2013-07-22T16:16:04Z<p>Seanmcbride: /* How to get keyboard events working on Mac OS X? */</p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk is 5.4.0 (released on 2009-3-26). This release for download available from:<br />
<br />
http://www.vtk.org/VTK/resources/software.html<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesisitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Can I contribute money? ===<br />
<br />
Please don't send money. Not that we think you're going to send in<br />
unsolicited money. But if you were thinking about it, stop. It would<br />
just complicate our lives and make for all sorts of tax problems.<br />
<br />
(Note: if you are a company or funding institution, and would like to fund<br />
features or development, please contact Kitware http://www.kitware.com .)<br />
<br />
=== Is there a mailing list or Usenet newsgroup for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
There is also a newsgroup that mirrors the mailinglist. At this point it<br />
seems that mirror is down. Mail to the mailinglist used to be posted the<br />
newsgroup, but posts on the newsgroup were not sent to the mailinglist.<br />
The newsgroup was located at:<br />
news://scully.esat.kuleuven.ac.be/vtk.mailinglist<br />
<br />
http://www.gmane.org is a bidirectional mail-to-news gateway that carries the vtkusers mailing list. Its located here: news://news.gmane.org/gmane.comp.lib.vtk.user or here: http://news.gmane.org/gmane.comp.lib.vtk.user. vtkusers mails have been archived since April 2002 and they never expire. You can read and send mails to the vtkusers list but sent mail will bounce back without having subscribed to the list first.<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://public.kitware.com/dashboard.php?name=vtk<br />
<br />
VTK uses Dart to perform builds, run tests, and generate dashboards. You<br />
can find more information about Dart at: http://public.kitware.com/Dart/<br />
<br />
You can help improve the quality of VTK by supplying the authors with<br />
Tcl scripts that can be used as or turned into regression tests. A good<br />
regression test will:<br />
<br />
# Cover code that is not already covered.<br />
# Illustrate a bug that is occuring now or that has occurred in the past.<br />
# Use data that is on the 2nd Edition book CDROM or use "small" data files or use no data at all.<br />
# Optionally, produce an interesting result. <br />
<br />
Currently almost all regression tests are written in Tcl.<br />
<br />
Please send your Tcl regression tests to:<br />
mailto:wlorens1@mail.nycap.rr.com<br />
<br />
Bill will evaluate them for applicability and integrate them into the<br />
nightly test process.<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are six things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# Check out some of the material at [[VTK Courses, Classes, Presentations]].<br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and [[VTK/Examples|look at the examples]] (there are hundreds). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled [[http://www.catb.org/~esr/faqs/smart-questions.html How to ask questions the smart way]]. [[http://www.mikeash.com/getting_answers.html Getting Answers]] is a good starting point too.<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Avoid HTML emails.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
bacause the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Accessing VTK CVS from behind a firewall ===<br />
<br />
Use the sourceforge project:<br />
<br />
http://cvsgrab.sourceforge.net/<br />
<br />
Just download the script and type something like:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xx<br />
<br />
(Thanks to Ingo H. de Boer)<br />
<br />
Also cvsgrab support the following option to access a particular branch:<br />
<br />
-tag <version tag> [optional] The version tag of the files to download<br />
<br />
For example to get the latest 4.4 branch:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xxx<br />
-tag release-4-4<br />
<br />
=== Where can I obtain test and sample datasets? ===<br />
<br />
See [[VTK Datasets|this page]] for details on downloading datasets that VTK can read.<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# 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.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
* [http://public.kitware.com/pipermail/vtkusers/2003-October/070054.html vtk, Python and SWIG - 'state of the union']<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# 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''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
==== GDCM ====<br />
<br />
For a more elaborate DICOM library that supports more image format, you might try [http://gdcm.sourceforge.net GDCM].<br />
Specifically: [http://gdcm.sourceforge.net/html/classvtkGDCMImageReader.html vtkGDCMImageReader] & [http://gdcm.sourceforge.net/html/classvtkGDCMImageWriter.html vtkGDCMImageWriter]<br />
<br />
Grassroots DiCoM is a C++ library for DICOM medical files. It is automatically wrapped to python/C#/Java (using swig). It supports RAW,JPEG (lossy/lossless),J2K,JPEG-LS,RLE and deflated. It also comes with DICOM Part 3,6 & 7 of the standard as XML files.<br />
<br />
If GDCM is too complex to integrate in your environment you can also consider simply using the command line converter: [http://apps.sourceforge.net/mediawiki/gdcm/index.php?title=Gdcmconv gdcmconv] to convert an unsupported DICOM file into something that vtkDICOMImageReader, can support. Typically you would want:<br />
<br />
gdcmconv --raw compressed_input.dcom uncompressed_output.dcom<br />
<br />
==== dicom2 ====<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== vtkVolume16Reader ====<br />
<br />
When searching the vtkusers mailing list a lot of posts are still using vtkVolume16Reader to read in DICOM file. It will works in the following case:<br />
* You know the dimension (cols & rows) of your image<br />
* You know the spacing of your image<br />
* You know the pixel type (pixel type & #components) of your image<br />
* You know Pixel Data (7fe0,0010) is the last element in the image<br />
* You know Pixel Data (7fe0,0010) was sent in uncompressed format (not encapsulated)<br />
<br />
All those requirements are a stronger set of requirements than vtkDICOMImageReader, therefore it is encourage to use vtkDICOMImageReader instead.<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
GDCM 1.x:<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
GDCM 2.x:<br />
IPPSorter ipp;<br />
ipp.Sort( filenames );<br />
zspacing = ipp.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
==== Using ReleaseDataFlag ====<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
==== Use ImmediateModeRendering ====<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
==== Use triangle strips via vtkStripper. ====<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
==== Use a different filter or mapper ====<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use the STL.<br />
However, see the [[VTK Coding Standards]] for limitations.<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
==== Vim indentation ====<br />
<br />
[[user talk:Andy|Andy Cedilnik]] has some information on following the VTK coding guidelines using vim. You may place the following in your <code>~/.vimrc</code> file<br />
set tabstop=2 " Tabs are two characters<br />
set shiftwidth=2 " Indents are two charactes too<br />
set expandtab " Do not use tabs<br />
set cinoptions={1s,:0,l1,g0,c0,(0,(s,m1<br />
"Keep tabs in makefiles as they are significant:<br />
:autocmd BufRead,BufNewFile [Mm]akefile :set noexpandtab<br />
<br />
=== How to display transparent objects? ===<br />
(keywords: alpha, correct, depth, geometry, object, opacity, opaque, order, ordering, peel, peeling, sorting, translucent, transparent.)<br />
<br />
When opaque geometry is rendered, there is no need to sort it because the depth buffer (or z-buffer) is used and the sorting is done automatically by keeping the geometry closest to the viewpoint at<br />
a given pixel. (It is easy because it is a MAX/MIN calculation, not a real sorting).<br />
<br />
With translucent geometry the final color of a pixel is the contribution of all the geometry primitives visible through the pixel. The color of the pixel is the result of <b>a</b> blending operation between the colors of all visible primitives. Blending operations themselves are usually order-dependent (ie not commutative). That's why depth sorting is required. There are two ways to fix the ordering in VTK:<br />
<br />
*1. Append all your polygonal geometry with [http://www.vtk.org/doc/nightly/html/classvtkAppendPolyData.html vtkAppendPolyData] and pass it to [http://www.vtk.org/doc/nightly/html/classvtkDepthSortPolyData.html vtkDepthSortPolyData]. See this tcl [http://public.kitware.com/cgi-bin/viewcvs.cgi/*checkout*/Hybrid/Testing/Tcl/depthSort.tcl?root=VTK&content-type=text/plain example]. Depth sorting is done per centroid of geometry primitives, not per pixel. For this reason it is not exact but it solves <b>most</b> of the ordering and gives result usually good enough.<br />
* 2. If the graphics card supports it, use "[[VTK/Depth_Peeling | depth peeling]]". It performs per pixel sorting (better result) but it is really slow.<br />
<br />
=== What's the deal with SetInput() vs. SetInputConnection()? ===<br />
(keywords: SetInput, SetInputConnection, vtkAlgorithm, algorithm, pipeline, source)<br />
<br />
In the transition from VTK 4 to VTK 5, the VTK pipeline executive was completely cleaned up and redesigned. The fundamental idea behind the new pipeline is that the "pipeline" should consist of a chain of "algorithm" objects.<br />
The algorithms are connected together with the familiar b->SetInputConnection(a->GetOutputPort()) methods.<br />
<br />
So how is this different from SetInput()/GetOutput()? The difference between an "OutputPort" and an "Output" is as follows:<br />
<br />
* OutputPort (''vtkAlgorithmOutput''): A trivial object that says "I am output port N of algorithm X" (usually N = 0).<br />
* Output (''subclass of vtkDataObject''): A container for data produced by any VTK code.<br />
<br />
The "OutputPort" method does not presuppose anything about what data (if any) will pass along the pipeline. It could simply signify that algorithm "a" must execute before algorithm "b". This provides enormous flexibility. Trust the VTK designers here, it's better to do things this way than to have the user grab the actual data object from the output of one algorithm and shove it into the input of another.<br />
<br />
However, any newcomer to VTK will quickly notice that the use of SetInputConnection() is not universal. The reason is this: only vtkAlgorithm objects can have a SetInputConnection() or GetOutputPort() method. Some objects that can take inputs are not derived from vtkAlgorithm. For example vtkImageActor is a vtkProp3D and therefore it cannot be a vtkAlgorithm (VTK never uses multiple inheritance). This is a case of an old VTK object that doesn't "fit" the new VTK 5 pipeline. However, the VTK developers did not want to throw away such useful classes when the pipeline was redesigned. Instead, such classes are still served by the backwards-compatible SetInput() method.<br />
<br />
So, use SetInputConnection() whenever you can, but if there is no SetInputConnection(), then go ahead and use SetInput(). There is nothing wrong with doing so. The new pipeline is backwards compatible with the old pipeline methods.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows and Mac workstations.<br />
<br />
=== What Graphics Cards work with VTK ===<br />
<br />
VTK uses OpenGL to perform almost all of its rendering and some graphics cards/drivers have better support for OpenGL than others. This is not a listing of what cards perform well. It is a listing of what cards actually produce correct results. Here is a list of cards and their status roughly in best to worst order.<br />
<br />
* Any Nvidia desktop card on Windows -- 100% compatible<br /> <br />
* Any ATI desktop cards on Windows -- 100% compatible<br /><br />
* Mesa -- most releases pass all VTK tests<br /><br />
* Microsoft Software OpenGL -- passes all VTK tests but does have a couple bugs<br /><br />
* Mac graphics cards -- these usually pass all VTK tests. Older cards may have some issues, for example, the ATI Rage 128 Pro does not support textures larger than 1024x1024.<br /><br />
* Non-linux UNIX cards (Sun HP SGI) -- These generally work<br /><br />
* Any Nvidia card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Any ATI card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Nvidia laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests<br /><br />
* ATI laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests (e.g. [http://public.kitware.com/pipermail/vtkusers/2004-August/075966.html ATI Mobility Radeon 9600])<br /><br />
* Intel Extreme Graphics -- fails some VTK tests<br /><br />
<br />
=== How do I build the examples on the PC running Windows? ===<br />
<br />
Since building the C++ examples on the PC isn't all that easy, here are<br />
some instructions from Jack McInerney.<br />
<br />
Steps for creating a VTK C++ project 8/14/96<br />
<br />
This is based on what I learned creating a project to run the Mace<br />
example. These steps allowed me to successfully built and run this example.<br />
<br />
# Create a console project (File, New, then select Console application).<br />
# Add the files of interest to the project. (e.g., Mace.cxx)<br />
# Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies<br /> 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<br />
# 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).<br />
# 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 <br /> This is a self extracting archive which contains these files. Simply place them in your windows system directory.<br />
# Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless<br /><br />
<br />
When you go to run the program, it will bomb out unless it can find 2<br />
DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the<br />
project directory or the C:\WINDOWS directory. These files are supplied<br />
on the vtk CD-ROM (in the vtk\bin directory).<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
vtk builds on 64 bit systems, that is, systems where sizeof(void*) is 64 bits. However, parts of the vtk codebase are not 64 bit clean and so runtime problems are likely if that code is used.<br />
<br />
===== General =====<br />
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.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5 and later, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work well with 64 bit Cocoa on Mac OS X 10.5 and later.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== What size swap space should I use on a PC? ===<br />
<br />
Building vtk on the PC requires a significant amount of memory (at least<br />
when using Visual C++)... but the final product is nice and compact. To<br />
build vtk on the PC, we recommend setting the min/max swap space to at<br />
least 400MB/500MB (depending on how much RAM you have... the sum of RAM<br />
and swap space should be roughly 500+ MB).<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
See http://paraview.org/Wiki/ParaView_And_Mesa_3D.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
See [[Cocoa_VTK]] for details if you are having trouble getting keyboard events working.<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.4 and older, the short answer is no. For more recent versions, certainly 5.6 and later, the answer is yes.<br />
<br />
You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. For example:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
=== How can a user process access more than 2 GB of ram in 32-bit Windows? ===<br />
<br />
By default on Windows, the most memory that a user process can access is 2 GB, no matter how much RAM you have installed in your system. With Windows XP Professional you can make it possible for a process to use up to 3 GB of memory by doing two things:<br />
<br />
1) Modify the boot parameters in boot.ini (on my 32 bit WinXP Pro machine, it's in: "C:\boot.ini") to tell the operating system that you want user processes to have access to up to 3GB of RAM (This is a really important file, and if you don't know what you are doing, stop reading this and go back to work!). This is done by adding the /3GB flag to the line of the file that tells the boot loader where the operating system is. My boot.ini file looks like:<br />
<br />
[boot loader]<br />
timeout=30<br />
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS<br />
[operating systems]<br />
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /3GB<br />
<br />
This is a very bad file to make mistakes on, so don't - it may be very difficult to repair your computer to boot if you mess up this file. There is a nice description of this in the Microsoft article <br />
[http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx Memory Support and Windows Operating Systems].<br />
<br />
2) The other thing that you need to do is make your executable LARGEADDRESSAWARE. Assuming that you have a Windows binary that you want to try this on, you can use the 'editbin' utility that comes with Visual Studio to change the setting of one bit (the IMAGE_FILE_LARGE_ADDRESS_AWARE bit) in the image header of the executable. For a program 'prog.exe' you can make the change by<br />
<br />
editbin /LARGEADDRESSAWARE prog.exe<br />
<br />
Of course, depending on how your program handles memory you might find that it crashes when you try to use the extra memory, but that's a separate issue. If you are compiling your program with a version of Visual Studio you should be able to find the switch to make your program /LARGEADDRESSAWARE.<br />
<br />
=== Shared builds of VTK and debugging QVTKWidget using Visual Studio ===<br />
<br />
Assuming that you have built a shared build of VTK and you may or may<br />
not have a set it up such that there is a path to the release version<br />
of VTK in your PATH statement.<br />
<br />
Then if you debug a project that is using QVTKWidget, you will come<br />
across a problem in that if you are debugging a debug version; the<br />
application depends upon the debug version of QVTK.dll which will<br />
depend upon QtGui4d.dll (among others) and load it. But, because the<br />
release version of QVTK.dll is in the path, QtGiu4.dll will also be<br />
loaded preventing the application from running. You will get a<br />
"QWidget: Must construct a QApplication before a QPaintDevice"<br />
message.<br />
<br />
The solution to this problem is to set the path to the correct build<br />
of VTK on the "'''Debugging'''" properties of your project. Right click on<br />
your project, bring up the properties dialog, and select "'''Debugging'''"<br />
from the list on the left. There should be an "'''Environment'''" line. You<br />
can add variables here using key=value pairs.<br />
For example, add the following line:<br />
PATH=<Path To VTK>\bin\$(OutDir);%PATH%<br />
You can then add the same line to other configurations, such as the release one, by selecting<br />
them from the top left drop down box labelled '''Configuration'''.<br />
<br />
$(OutDir) will be set by Visual Studio to either Debug or Release,<br />
depending upon what configuration you have selected. Make sure <br />
that ;%PATH% is appended so that Qt and other files can be appended <br />
to the PATH statement.<br />
<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes in VTK between 3.2 and 4.0 ===<br />
<br />
* 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.<br />
<br />
* 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<br />
<br />
* Added special methods to data arrays to replace methods like<br />
<br />
tc SetTCoord i x y 0<br />
<br />
or<br />
<br />
vc SetVector i vx vy vz<br />
<br />
in interpreted languages (Tcl, Python, Java). Use:<br />
<br />
tc SetTuple2 i x y<br />
<br />
or<br />
<br />
vc SetTuple3 i vx vy vz<br />
<br />
* 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.<br />
<br />
* vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.<br />
<br />
* 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.<br />
<br />
* 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).<br />
<br />
* The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.<br />
<br />
* Support for reading and writing PGM and JPEG images has been included.<br />
<br />
* 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.<br />
<br />
* 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 Imaging 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.<br />
<br />
* 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.<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* 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.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* 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.<br />
<br />
* 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:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== How do I upgrade my existing C++ code from 3.2 to 4.x? ===<br />
<br />
This is (a corrected version of) an email that was posted to vtkusers.<br />
Please feel free to correct or add anything.<br />
<br />
{| cellspacing="3" <br />
|- valign="top"<br />
|width="55%" bgcolor="#f0f0ff" style="border:1px solid #ffc9c9;padding:1em;padding-top:0.5em;"|<br />
<br />
I've just ported my medium-sized (40K lines) application from vtk3.2 to<br />
vtk4.x. I thought I would share my experiences with you, in case there<br />
were people out there contemplating it but a bit scared.<br />
<br />
One source of information for upgrading code is:<br />
<br />
http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the<br />
script in the zip file.<br />
<br />
So,<br />
<br />
I switched all my include directories to the new VTK ones and<br />
recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and<br />
vtkTCoords which have both been removed. Where I was using single value<br />
scalars, like this:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetNumberOfScalars(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetScalar(i,2.3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *scalars = vtkFloatArray::New();<br />
scalars->SetNumberOfComponents(1);<br />
scalars->SetNumberOfTuples(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetTuple1(i,2.3);<br />
...<br />
<br />
OK so far, far fewer errors.<br />
<br />
Where I had 2D texture coordinates:<br />
<br />
vtkTCoords *tcoords = vtkTCoords::New();<br />
tcoords->SetNumberOfTCoords(N);<br />
...<br />
float p[3];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTCoord(i,p);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *tcoords = vtkFloatArray::New();<br />
tcoords->SetNumberOfComponents(2);<br />
tcoords->SetNumberOfTuples(N);<br />
...<br />
float p[2];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTuple(i,p);<br />
....<br />
<br />
All well and good, still fewer errors. Make sure you call<br />
SetNumberOfComponents *before* SetNumberOfTuples else you'll get<br />
problems (I did!).<br />
<br />
Where I was creating 0-255 image data and had been using:<br />
<br />
vtkScalars* scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
...<br />
<br />
Going well!<br />
<br />
When creating RGB images, I had been using:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfScalars(X*Y);<br />
...<br />
scalars->SetActiveComponent(0);<br />
scalars->SetScalar(i,val1);<br />
scalars->SetActiveComponent(1);<br />
scalars->SetScalar(i,val2);<br />
scalars->SetActiveComponent(2);<br />
scalars->SetScalar(i,val3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfTuples(X*Y);<br />
...<br />
scalars->SetComponent(i,0,val1);<br />
scalars->SetComponent(i,1,val2);<br />
scalars->SetComponent(i,2,val3);<br />
...<br />
<br />
My remaining errors concerned vtkWin32OffscreenRenderWindow that has<br />
been removed. Where I had been using:<br />
<br />
vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New();<br />
offscreen->SetOffScreenRendering(1);<br />
...<br />
<br />
All done. I'd had to throw in some #include "vtkFloatArray.h" and things<br />
like that of course. Zero compile errors.<br />
<br />
Had to remember to link against the new vtk lib files, so I removed<br />
<br />
vtkdll.lib <br />
<br />
and added<br />
<br />
vtkCommon.lib<br />
vtkGraphics.lib<br />
<br />
etc.<br />
<br />
Zero link errors. My program is up and running again, no apparant<br />
problems. Plus now I can use all the new features of vtk4. (And I'm sure<br />
it's faster but maybe that's my imagination.)<br />
<br />
All this took me about three hours.<br />
<br />
Bye!<br />
<br />
Tim.<br />
|}<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was releaseed in February 2003. VTK 4.4 (which was an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, 5.0.3 in March 2007, and 5.0.4 in January 2008.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# 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.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* 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.<br />
#* 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.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* 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.<br />
* 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).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* 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. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* 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.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
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.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== Using Volume Rendering in VTK ===<br />
<br />
I recently updated my VTK CVS version. And my c++ code that use to work fine are now complaining about:<br />
<br />
undefined reference to `vtkUnstructuredGridAlgorithm::SetInput(vtkDataObject*)'<br />
undefined reference to `vtkUnstructuredGridAlgorithm::GetOutput()' <br />
<br />
There is now a new subfolder and a new option to enable building the VolumeRendering library. You have to turn VTK_USE_VOLUMERENDERING to ON in order to use it. Also make sure that your executable is linking properly to this new library:<br />
<br />
ADD_EXECUTABLE(foo foo.cxx)<br />
TARGET_LINK_LIBRARIES(foo vtkVolumeRendering)<br />
<br />
=== API Changes in VTK 5.2 ===<br />
<br />
==== <tt>vtkProp::RenderTranslucentGeometry()</tt> is gone ====<br />
<br />
<tt>vtkProp::RenderTranslucentGeometry()</tt> is gone and has been broken down into 3 methods:<br />
* <tt>HasTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderVolumetricGeometry()</tt><br />
<br />
Here is what to change in a vtkProp subclass:<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry only, override <tt>HasTranslucentPolygonalGeometry()</tt> and <tt>RenderTranslucentPolygonalGeometry()</tt>. <b>Just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderTranslucentPolygonalGeometry()</tt> is not enough!</b><br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent volumetric geometry only, override <tt>RenderVolumetricGeometry()</tt>. In this case, just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderVolumetricGeometry()</tt> is OK.<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry and translucent volumetric geometry, override all 3 methods.<br />
<br />
The reason of this change is that <tt>HasTranslucentPolygonalGeometry()</tt> is used to decide if an expensive initialization of the new rendering algorithm of translucent polygonal geometry (depth peeling) is necessary. <tt>RenderTranslucentPolygonalGeometry()</tt> is called multiple times during the rendering of the translucent polygonal geometry of the scene. <tt>RenderVolumetricGeometry()</tt> is called in an additional pass, after depth peeling. For this reason, <b><tt>RenderTranslucentGeometry()</tt> cannot just be marked as deprecated but had to be removed from the API</b>.<br />
<br />
<br />
<br />
==== <tt>vtkImagePlaneWidget</tt> has action names changed ====<br />
from:<br />
enum<br />
{<br />
CURSOR_ACTION = 0,<br />
SLICE_MOTION_ACTION = 1,<br />
WINDOW_LEVEL_ACTION = 2<br />
};<br />
to:<br />
enum<br />
{<br />
VTK_CURSOR_ACTION = 0,<br />
VTK_SLICE_MOTION_ACTION = 1,<br />
VTK_WINDOW_LEVEL_ACTION = 2<br />
};<br />
<br />
==== <tt>GetOutput()</tt> now returns <tt>vtkDataObject</tt> for some algorithms ====<br />
<br />
The following algorithms now work on <tt>vtkGraph</tt> as well as <tt>vtkDataSet</tt>, so no <tt>GetOutput()</tt> longer returns <tt>vtkDataSet</tt>. To obtain the dataset, use <tt>vtkDataSet::SafeDownCast(filter->GetOutput())</tt><br />
* <tt>vtkArrayCalculator</tt><br />
* <tt>vtkAssignAttribute</tt><br />
* <tt>vtkProgrammableFilter</tt><br />
<br />
=== API Changes in VTK 5.4 ===<br />
* empty right now.<br />
=== API Changes in VTK 5.5 ===<br />
<br />
* vtkStreamTracer<br />
Changed<br />
enum Units <br />
{ <br />
TIME_UNIT, <br />
LENGTH_UNIT, <br />
CELL_LENGTH_UNIT <br />
}<br />
to<br />
enum Units<br />
{ <br />
LENGTH_UNIT = 1, <br />
CELL_LENGTH_UNIT = 2 <br />
}<br />
<br />
<br />
Changed<br />
* OUT_OF_TIME = 4<br />
to<br />
* OUT_OF_LENGTH = 4<br />
in enum ''ReasonForTermination''<br />
<br />
<br />
Changed<br />
* LastUsedTimeStep<br />
to<br />
* LastUsedStepSize<br />
<br />
<br />
Changed<br />
* MaximumPropagation<br />
* MaximumIntegrationStep<br />
* MinimumIntegrationStep<br />
* InitialIntegrationStep <br />
from type ''IntervalInformation'' to type ''double''.<br />
<br />
<br />
Added a member variable to the class<br />
* int IntegrationStepUnit<br />
<br />
<br />
The following APIs were '''removed''' from the class:<br />
* void SetMaximumProgration(int unit, double max)<br />
* void SetMaximumProgrationUnit(int unit)<br />
* int GetMaximumPropagationUnit()<br />
* void SetMaximumPropagationUnitToTimeUnit()<br />
* void SetMaximumPropagationUnitToLengthUnit()<br />
* void SetMaximumPropagationUnitToCellLengthUnit()<br />
* void SetMinimumIntegrationStep(int unit, double step)<br />
* void SetMinimumIntegrationStepUnit(int unit)<br />
* int GetMinimumIntegrationStepUnit()<br />
* void SetMinimumIntegrationStepUnitToTimeUnit()<br />
* void SetMinimumIntegrationStepUnitToLengthUnit()<br />
* void SetMinimumIntegrationStepUnitToCellLengthUnit()<br />
* void SetMaximumIntegrationStep(int unit, double step)<br />
* void SetMaximumIntegrationStepUnit(int unit)<br />
* int GetMaximumIntegrationStepUnit()<br />
* void SetMaximumIntegrationStepUnitToTimeUnit()<br />
* void SetMaximumIntegrationStepUnitToLengthUnit()<br />
* void SetMaximumIntegrationStepUnitToCellLengthUnit()<br />
* void SetInitialIntegrationStep(int unit, double step)<br />
* void SetInitialIntegrationStepUnit(int unit)<br />
* int GetInitialIntegrationStepUnit()<br />
* void SetInitialIntegrationStepUnitToTimeUnit()<br />
* void SetInitialIntegrationStepUnitToLengthUnit()<br />
* void SetInitialIntegrationStepUnitToCellLengthUnit()<br />
* void SetIntervalInformation(int unit, double interval, IntervalInformation& currentValues)<br />
* void SetIntervalInformation(int unit,IntervalInformation& currentValues)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength, double speed)<br />
* static double ConvertToTime(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToCellLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToUnit(IntervalInformation& interval, int unit, double cellLength, double speed)<br />
<br />
<br />
The following APIs were added to the class:<br />
* int GetIntegrationStepUnit()<br />
* void SetIntegrationStepUnit(int unit)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength)<br />
* static double ConvertToLength(double interval, int unit, double cellLength)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength)<br />
<br />
<br />
* vtkInterpolatedVelocityField<br />
Added a new member variable and two associated functions:<br />
* bool NormalizeVector<br />
* vtkSetMacro(NormalizeVector, bool)<br />
* vtkGetMacro(NormalizeVector, bool)<br />
<br />
== OpenGL requirements ==<br />
<br />
=== Terminology ===<br />
<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
<br />
==== Linux/Unix ====<br />
<br />
Two ways:<br />
<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
<br />
* vendor specific tool<br />
<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
=== VTK 5.2 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.2? ====<br />
<br />
Same answer than for VTK 5.0.<br />
<br />
==== What is the minimal OpenGL version required by VTK5.2 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>, <tt>vtkHAVSVolumeMapper</tt>,<br />
<tt>vtkGLSLShaderProgram</tt>, depth peeling and some hardware offscreen rendering using framebuffer objects (FBO).<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
If you want to use <tt>vtkHAVSVolumeMapper</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_draw_buffers</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_program</tt><br />
* <tt>GL_ARB_vertex_program</tt><br />
* <tt>GL_EXT_framebuffer_object</tt><br />
* either <tt>GL_ARB_texture_float</tt> or <tt>GL_ATI_texture_float</tt><br />
<br />
The following extension or OpenGL version is used by <tt>vtkHAVSVolumeMapper</tt> if provided (at runtime), but it is optional:<br />
* <tt>GL_ARB_vertex_buffer_object</tt> or OpenGL>=1.5<br />
<br />
If you want to use <tt>vtkGLSLShaderProgram</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_shading_language_100</tt> or OpenGL>=2.0,<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0.<br />
<br />
Depth peeling ( see [[VTK/Depth_Peeling | VTK Depth Peeling]] for more information) requires (at runtime):<br />
* <tt>GL_ARB_depth_texture</tt> or OpenGL>=1.4<br />
* <tt>GL_ARB_shadow</tt> or OpenGL>=1.4<br />
* <tt>GL_EXT_shadow_funcs</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_occlusion_query</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
* <tt>GL_SGIS_texture_edge_clamp</tt> or <tt>GL_EXT_texture_edge_clamp</tt> or OpenGL>=1.2<br />
<br />
Hardware-based offscreen rendering using framebuffer object (FBO) will be used as the default offscreen method if the following extensions or OpenGL version are available (at runtime):<br />
* <tt>GL_EXT_framebuffer_object</tt><br />
and either <br />
* <tt>GL_ARB_texture_non_power_of_two</tt> or OpenGL>=2.0<br />
or<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
In addition, if the the framebuffer needs a stencil buffer, extension <tt>GL_EXT_packed_depth_stencil</tt> is required. Even if all those extensions are supported, the chosen FBO format might<br />
not be supported by the card; in this case, this method of offscreen rendering is not used.<br />
<br />
== Miscellaneous questions ==<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
== Legal issues ==<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Development]]<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. We think it's pretty reasonable. We do restrict the<br />
distribution of modified code. This is primarily a revision control<br />
issue. We don't want a bunch of renegade vtks running around without us<br />
having some idea why the changes were made and giving us a chance to<br />
incorporate them into the general release.<br />
<br />
The text of the VTK copyright is available [http://www.vtk.org/copyright.php here].<br />
<br />
=== What is the deal with the patents ===<br />
<br />
As the copyright mentions there are some patents used in VTK. If you use<br />
any code in the Patented/ directory for commercial application you<br />
should contact the patent holder and obtain a license.<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by General Electric Company: vtkDecimate, vtkMarchingCubes,<br />
vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface.<br />
The GE contact is:<br />
<br />
Carl B. Horton<br />
Sr. Counsel, Intellectual Property<br />
3000 N. Grandview Blvd., W-710<br />
Waukesha, WI 53188<br />
Phone: (262) 513-4022<br />
E-Mail: mailto:Carl.Horton@med.ge.com<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by Kitware, Inc.: vtkGridSynchronizedTemplates3D,<br />
vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and<br />
vtkSynchronizedTemplates3D. The Kitware contact is:<br />
<br />
Ken Martin<br />
Kitware<br />
28 Corporate Drive, Suite 204,<br />
Clifton Park, NY 12065<br />
Phone:1-518-371-3971<br />
E-Mail: mailto:kitware@kitware.com<br />
<br />
=== Can VTK be used as part of a project distributed under a GPL License ? ===<br />
<br />
==== Short Answer ====<br />
<br />
Yes, it is fine to take VTK code and to include it in a project that is distributed under a GPL license.<br />
<br />
==== Long Answer ====<br />
<br />
===== Terms =====<br />
<br />
Let's call project X the larger project that:<br />
<br />
# Will include source code from VTK (in part or as a whole)<br />
# Will be distributed under GPL license<br />
<br />
Note in particular that:<br />
<br />
# The copyright notices in VTK files must be kept.<br />
# If VTK files are modified by the developers of project X, that fact must be clearly indicated.<br />
# Only the modifications of VTK files made by the developers of project X will be covered by a GPL license. The original VTK code remains covered by the VTK license.<br />
# The collection of copyrighted works (project X in this case), that includes VTK (in part or as a whole) and their software will be covered by a GPL license.<br />
<br />
===== Details =====<br />
<br />
As the [http://www.vtk.org/copyright.php VTK license] is a variation of the [http://www.opensource.org/licenses/bsd-license.php Modified BSD license], to which only the following term has been added:<br />
<br />
Modified source versions must be plainly marked as such, <br />
and must not be misrepresented as being the original software.<br />
<br />
and that the Modified BSD license is itself compatible with the GPL <br />
<br />
http://www.gnu.org/philosophy/license-list.html (Modified BSD license)<br />
<br />
Then the VTK license is also compatible with the GPL license. Since the terms of the GPL license do not preclude the additional term of the VTK license from being followed.<br />
<br />
NOTE: The licenses are only '''one way compatible'''.<br />
<br />
* You can use VTK code inside a GPL licensed project.<br />
* You '''can not''' use GPL licensed code inside VTK.<br />
<br />
That is the reason why there are no GPL third party libraries in VTK. Having GPL third party libraries in VTK would prevent closed source projects from being built against VTK.<br />
<br />
== Common problems and their solutions ==<br />
* There are some problems may that arise while building VTK that have very straight forward solutions. [[VTK/BuildingProblems|Here]] they are.<br />
* There are some problems that arise frequently that have very straight forward solutions. [[VTK/CommonProblems|Here]] they are.<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=Cocoa_VTK&diff=53350Cocoa VTK2013-07-22T16:12:05Z<p>Seanmcbride: Complete rewrite and modernisation.</p>
<hr />
<div>As VTK is cross-platform, building on Mac OS X is much the same as on any other supported platform. This page only discusses some OS X-specific topics related to VTK 5.10 and later. For information on antique versions of VTK, refer to the version of this page in the history from 2013-07-21 or earlier.<br />
<br />
== '''Supported Versions''' ==<br />
VTK 6.0 supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.5 or later.<br />
<br />
VTK 5.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.4 or later.<br />
<br />
On OS X 10.5, you should use at least VTK 5.4.2. On OS X 10.6, at least VTK 5.6. On OS X 10.7 and later, VTK 6 is recommended.<br />
<br />
== '''Windowing API''' ==<br />
<br />
On OS X, there are two windowing APIs: Carbon and Cocoa. Older versions of VTK defaulted to Carbon, but newer versions default to Cocoa. Carbon support is deprecated by both Apple and VTK, and should not be used for new development. To choose, set one of the following to ON:<br />
<br />
VTK_USE_CARBON:BOOL=ON<br />
VTK_USE_COCOA:BOOL=ON<br />
<br />
== '''Deployment Target and SDK''' ==<br />
<br />
The 'deployment target' and 'SDK' are concepts that should be familiar to OS X developers. In brief, the 'deployment target' specifies the oldest version of OS X that you which to support at runtime; it should always be set. Ex:<br />
<br />
CMAKE_OSX_DEPLOYMENT_TARGET:STRING=10.7<br />
<br />
The 'SDK' specifies which version of OS headers and libraries you want to build against. Usually, you want to built against the newest SDK, which is what CMake defaults to. But you can override it:<br />
<br />
CMAKE_OSX_SYSROOT:STRING=/path/to/SDK<br />
<br />
== '''Universal Binaries''' ==<br />
<br />
VTK can be built as a universal binary, that is, as libraries that have executable code for several CPU types. Even if you want to build for only one CPU type, you should always specify them explicitly, ex:<br />
<br />
CMAKE_OSX_ARCHITECTURES:STRING=i386;x86_64<br />
<br />
Possible values are: ppc, ppc64, i386, and x86_64.<br />
<br />
== '''Cocoa Memory Management Models''' ==<br />
<br />
Cocoa has three memory management models, chronologically by date of introduction:<br />
<br />
* manual reference counting (MRC)<br />
* garbage collection (GC)<br />
* automatic reference counting (ARC)<br />
<br />
VTK supports MRC and GC. ARC support will eventually be available in VTK 6.x.<br />
<br />
MRC is the default. GC was deprecated in OS X 10.8, but to use it set:<br />
<br />
VTK_REQUIRED_OBJCXX_FLAGS:STRING=-fobjc-gc<br />
<br />
== '''VTK_USE_SYSTEM options''' ==<br />
<br />
VTK has several VTK_USE_SYSTEM_* options, allowing you to link against the OS's built-in versions of popular third party libraries. On OS X, the only one included by OS X is [http://www.zlib.net zlib], which you can make VTK use by setting:<br />
<br />
VTK_USE_SYSTEM_ZLIB:BOOL=ON<br />
<br />
== '''Use Application Bundles''' ==<br />
<br />
On OS X, there are (at least) two kinds of executables:<br />
* Application Bundles<br />
* plain UNIX executables<br />
To be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction), OS X requires you to use an application bundle. If a plain UNIX executable tries, it will mostly work, but there will be various bugs, such as keyboard and mouse events not working properly.<br />
Many, but not all, of the VTK examples are built as plain UNIX executables, and thus have these problems. This is [http://vtk.org/Bug/view.php?id=2025 bug 2025].<br />
When you build your own VTK application, it is best to make it in the form of an application bundle. Simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an application bundle, see [http://vtk.org/Bug/view.php?id=2025 bug 2025] for possible workarounds.<br />
<br />
== '''SimpleCocoaVTK''' ==<br />
<br />
SimpleCocoaVTK is a sample Cocoa application written by Sean McBride and Mike Jackson that uses VTK. It illustrates how to use the VTK libraries within an Xcode-based OS X application. SimpleCocoaVTK is an example, it is not required to use VTK.<br />
<br />
Originally standalone, SimpleCocoaVTK is now part of VTK itself in the [http://vtk.org/gitweb?p=VTK.git;a=tree;f=Examples/GUI/Cocoa Examples/GUI/Cocoa] folder. See the documentation there for how to use it.<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=53236VTK/FAQ2013-07-22T15:12:47Z<p>Seanmcbride: /* Can VTK be built as a Universal Binary on Mac OS X? */</p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk is 5.4.0 (released on 2009-3-26). This release for download available from:<br />
<br />
http://www.vtk.org/VTK/resources/software.html<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesisitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Can I contribute money? ===<br />
<br />
Please don't send money. Not that we think you're going to send in<br />
unsolicited money. But if you were thinking about it, stop. It would<br />
just complicate our lives and make for all sorts of tax problems.<br />
<br />
(Note: if you are a company or funding institution, and would like to fund<br />
features or development, please contact Kitware http://www.kitware.com .)<br />
<br />
=== Is there a mailing list or Usenet newsgroup for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
There is also a newsgroup that mirrors the mailinglist. At this point it<br />
seems that mirror is down. Mail to the mailinglist used to be posted the<br />
newsgroup, but posts on the newsgroup were not sent to the mailinglist.<br />
The newsgroup was located at:<br />
news://scully.esat.kuleuven.ac.be/vtk.mailinglist<br />
<br />
http://www.gmane.org is a bidirectional mail-to-news gateway that carries the vtkusers mailing list. Its located here: news://news.gmane.org/gmane.comp.lib.vtk.user or here: http://news.gmane.org/gmane.comp.lib.vtk.user. vtkusers mails have been archived since April 2002 and they never expire. You can read and send mails to the vtkusers list but sent mail will bounce back without having subscribed to the list first.<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://public.kitware.com/dashboard.php?name=vtk<br />
<br />
VTK uses Dart to perform builds, run tests, and generate dashboards. You<br />
can find more information about Dart at: http://public.kitware.com/Dart/<br />
<br />
You can help improve the quality of VTK by supplying the authors with<br />
Tcl scripts that can be used as or turned into regression tests. A good<br />
regression test will:<br />
<br />
# Cover code that is not already covered.<br />
# Illustrate a bug that is occuring now or that has occurred in the past.<br />
# Use data that is on the 2nd Edition book CDROM or use "small" data files or use no data at all.<br />
# Optionally, produce an interesting result. <br />
<br />
Currently almost all regression tests are written in Tcl.<br />
<br />
Please send your Tcl regression tests to:<br />
mailto:wlorens1@mail.nycap.rr.com<br />
<br />
Bill will evaluate them for applicability and integrate them into the<br />
nightly test process.<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are six things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# Check out some of the material at [[VTK Courses, Classes, Presentations]].<br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and [[VTK/Examples|look at the examples]] (there are hundreds). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled [[http://www.catb.org/~esr/faqs/smart-questions.html How to ask questions the smart way]]. [[http://www.mikeash.com/getting_answers.html Getting Answers]] is a good starting point too.<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Avoid HTML emails.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
bacause the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Accessing VTK CVS from behind a firewall ===<br />
<br />
Use the sourceforge project:<br />
<br />
http://cvsgrab.sourceforge.net/<br />
<br />
Just download the script and type something like:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xx<br />
<br />
(Thanks to Ingo H. de Boer)<br />
<br />
Also cvsgrab support the following option to access a particular branch:<br />
<br />
-tag <version tag> [optional] The version tag of the files to download<br />
<br />
For example to get the latest 4.4 branch:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xxx<br />
-tag release-4-4<br />
<br />
=== Where can I obtain test and sample datasets? ===<br />
<br />
See [[VTK Datasets|this page]] for details on downloading datasets that VTK can read.<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# 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.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
* [http://public.kitware.com/pipermail/vtkusers/2003-October/070054.html vtk, Python and SWIG - 'state of the union']<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# 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''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
==== GDCM ====<br />
<br />
For a more elaborate DICOM library that supports more image format, you might try [http://gdcm.sourceforge.net GDCM].<br />
Specifically: [http://gdcm.sourceforge.net/html/classvtkGDCMImageReader.html vtkGDCMImageReader] & [http://gdcm.sourceforge.net/html/classvtkGDCMImageWriter.html vtkGDCMImageWriter]<br />
<br />
Grassroots DiCoM is a C++ library for DICOM medical files. It is automatically wrapped to python/C#/Java (using swig). It supports RAW,JPEG (lossy/lossless),J2K,JPEG-LS,RLE and deflated. It also comes with DICOM Part 3,6 & 7 of the standard as XML files.<br />
<br />
If GDCM is too complex to integrate in your environment you can also consider simply using the command line converter: [http://apps.sourceforge.net/mediawiki/gdcm/index.php?title=Gdcmconv gdcmconv] to convert an unsupported DICOM file into something that vtkDICOMImageReader, can support. Typically you would want:<br />
<br />
gdcmconv --raw compressed_input.dcom uncompressed_output.dcom<br />
<br />
==== dicom2 ====<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== vtkVolume16Reader ====<br />
<br />
When searching the vtkusers mailing list a lot of posts are still using vtkVolume16Reader to read in DICOM file. It will works in the following case:<br />
* You know the dimension (cols & rows) of your image<br />
* You know the spacing of your image<br />
* You know the pixel type (pixel type & #components) of your image<br />
* You know Pixel Data (7fe0,0010) is the last element in the image<br />
* You know Pixel Data (7fe0,0010) was sent in uncompressed format (not encapsulated)<br />
<br />
All those requirements are a stronger set of requirements than vtkDICOMImageReader, therefore it is encourage to use vtkDICOMImageReader instead.<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
GDCM 1.x:<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
GDCM 2.x:<br />
IPPSorter ipp;<br />
ipp.Sort( filenames );<br />
zspacing = ipp.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
==== Using ReleaseDataFlag ====<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
==== Use ImmediateModeRendering ====<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
==== Use triangle strips via vtkStripper. ====<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
==== Use a different filter or mapper ====<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use the STL.<br />
However, see the [[VTK Coding Standards]] for limitations.<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
==== Vim indentation ====<br />
<br />
[[user talk:Andy|Andy Cedilnik]] has some information on following the VTK coding guidelines using vim. You may place the following in your <code>~/.vimrc</code> file<br />
set tabstop=2 " Tabs are two characters<br />
set shiftwidth=2 " Indents are two charactes too<br />
set expandtab " Do not use tabs<br />
set cinoptions={1s,:0,l1,g0,c0,(0,(s,m1<br />
"Keep tabs in makefiles as they are significant:<br />
:autocmd BufRead,BufNewFile [Mm]akefile :set noexpandtab<br />
<br />
=== How to display transparent objects? ===<br />
(keywords: alpha, correct, depth, geometry, object, opacity, opaque, order, ordering, peel, peeling, sorting, translucent, transparent.)<br />
<br />
When opaque geometry is rendered, there is no need to sort it because the depth buffer (or z-buffer) is used and the sorting is done automatically by keeping the geometry closest to the viewpoint at<br />
a given pixel. (It is easy because it is a MAX/MIN calculation, not a real sorting).<br />
<br />
With translucent geometry the final color of a pixel is the contribution of all the geometry primitives visible through the pixel. The color of the pixel is the result of <b>a</b> blending operation between the colors of all visible primitives. Blending operations themselves are usually order-dependent (ie not commutative). That's why depth sorting is required. There are two ways to fix the ordering in VTK:<br />
<br />
*1. Append all your polygonal geometry with [http://www.vtk.org/doc/nightly/html/classvtkAppendPolyData.html vtkAppendPolyData] and pass it to [http://www.vtk.org/doc/nightly/html/classvtkDepthSortPolyData.html vtkDepthSortPolyData]. See this tcl [http://public.kitware.com/cgi-bin/viewcvs.cgi/*checkout*/Hybrid/Testing/Tcl/depthSort.tcl?root=VTK&content-type=text/plain example]. Depth sorting is done per centroid of geometry primitives, not per pixel. For this reason it is not exact but it solves <b>most</b> of the ordering and gives result usually good enough.<br />
* 2. If the graphics card supports it, use "[[VTK/Depth_Peeling | depth peeling]]". It performs per pixel sorting (better result) but it is really slow.<br />
<br />
=== What's the deal with SetInput() vs. SetInputConnection()? ===<br />
(keywords: SetInput, SetInputConnection, vtkAlgorithm, algorithm, pipeline, source)<br />
<br />
In the transition from VTK 4 to VTK 5, the VTK pipeline executive was completely cleaned up and redesigned. The fundamental idea behind the new pipeline is that the "pipeline" should consist of a chain of "algorithm" objects.<br />
The algorithms are connected together with the familiar b->SetInputConnection(a->GetOutputPort()) methods.<br />
<br />
So how is this different from SetInput()/GetOutput()? The difference between an "OutputPort" and an "Output" is as follows:<br />
<br />
* OutputPort (''vtkAlgorithmOutput''): A trivial object that says "I am output port N of algorithm X" (usually N = 0).<br />
* Output (''subclass of vtkDataObject''): A container for data produced by any VTK code.<br />
<br />
The "OutputPort" method does not presuppose anything about what data (if any) will pass along the pipeline. It could simply signify that algorithm "a" must execute before algorithm "b". This provides enormous flexibility. Trust the VTK designers here, it's better to do things this way than to have the user grab the actual data object from the output of one algorithm and shove it into the input of another.<br />
<br />
However, any newcomer to VTK will quickly notice that the use of SetInputConnection() is not universal. The reason is this: only vtkAlgorithm objects can have a SetInputConnection() or GetOutputPort() method. Some objects that can take inputs are not derived from vtkAlgorithm. For example vtkImageActor is a vtkProp3D and therefore it cannot be a vtkAlgorithm (VTK never uses multiple inheritance). This is a case of an old VTK object that doesn't "fit" the new VTK 5 pipeline. However, the VTK developers did not want to throw away such useful classes when the pipeline was redesigned. Instead, such classes are still served by the backwards-compatible SetInput() method.<br />
<br />
So, use SetInputConnection() whenever you can, but if there is no SetInputConnection(), then go ahead and use SetInput(). There is nothing wrong with doing so. The new pipeline is backwards compatible with the old pipeline methods.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows and Mac workstations.<br />
<br />
=== What Graphics Cards work with VTK ===<br />
<br />
VTK uses OpenGL to perform almost all of its rendering and some graphics cards/drivers have better support for OpenGL than others. This is not a listing of what cards perform well. It is a listing of what cards actually produce correct results. Here is a list of cards and their status roughly in best to worst order.<br />
<br />
* Any Nvidia desktop card on Windows -- 100% compatible<br /> <br />
* Any ATI desktop cards on Windows -- 100% compatible<br /><br />
* Mesa -- most releases pass all VTK tests<br /><br />
* Microsoft Software OpenGL -- passes all VTK tests but does have a couple bugs<br /><br />
* Mac graphics cards -- these usually pass all VTK tests. Older cards may have some issues, for example, the ATI Rage 128 Pro does not support textures larger than 1024x1024.<br /><br />
* Non-linux UNIX cards (Sun HP SGI) -- These generally work<br /><br />
* Any Nvidia card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Any ATI card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Nvidia laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests<br /><br />
* ATI laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests (e.g. [http://public.kitware.com/pipermail/vtkusers/2004-August/075966.html ATI Mobility Radeon 9600])<br /><br />
* Intel Extreme Graphics -- fails some VTK tests<br /><br />
<br />
=== How do I build the examples on the PC running Windows? ===<br />
<br />
Since building the C++ examples on the PC isn't all that easy, here are<br />
some instructions from Jack McInerney.<br />
<br />
Steps for creating a VTK C++ project 8/14/96<br />
<br />
This is based on what I learned creating a project to run the Mace<br />
example. These steps allowed me to successfully built and run this example.<br />
<br />
# Create a console project (File, New, then select Console application).<br />
# Add the files of interest to the project. (e.g., Mace.cxx)<br />
# Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies<br /> 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<br />
# 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).<br />
# 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 <br /> This is a self extracting archive which contains these files. Simply place them in your windows system directory.<br />
# Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless<br /><br />
<br />
When you go to run the program, it will bomb out unless it can find 2<br />
DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the<br />
project directory or the C:\WINDOWS directory. These files are supplied<br />
on the vtk CD-ROM (in the vtk\bin directory).<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
vtk builds on 64 bit systems, that is, systems where sizeof(void*) is 64 bits. However, parts of the vtk codebase are not 64 bit clean and so runtime problems are likely if that code is used.<br />
<br />
===== General =====<br />
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.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5 and later, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work well with 64 bit Cocoa on Mac OS X 10.5 and later.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== What size swap space should I use on a PC? ===<br />
<br />
Building vtk on the PC requires a significant amount of memory (at least<br />
when using Visual C++)... but the final product is nice and compact. To<br />
build vtk on the PC, we recommend setting the min/max swap space to at<br />
least 400MB/500MB (depending on how much RAM you have... the sum of RAM<br />
and swap space should be roughly 500+ MB).<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
See http://paraview.org/Wiki/ParaView_And_Mesa_3D.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
On Mac OS X, there are (at least) two kinds of executables:<br />
* [http://developer.apple.com/documentation/MacOSX/Conceptual/BPInternational/Articles/InternatSupport.html#//apple_ref/doc/uid/20000278-73764 Application Bundles]<br />
* plain UNIX executables<br />
<br />
For a program to be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction) it really should be an Application Bundle. If a plain UNIX executable tries, there will be various bugs, such as keyboard and mouse events not working reliably.<br />
<br />
Many, but not all, of the example VTK applications are built as plain UNIX executables, and thus have these problems. This is [http://www.vtk.org/Bug/bug.php?op=show&bugid=2025 VTK bug 2025].<br />
<br />
When you build your own VTK application, it is best to make it in the form of an Application Bundle. With CMake 2.0.5 or later, simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an Application Bundle (perhaps because your app needs command line parameters) you might be able to avoid the above problems by adding an [http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/ConfigFiles.html#//apple_ref/doc/uid/20002091-SW1 __info_plist section] to your Mach-O executable. If you succeed, please post to the VTK list.<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.4 and older, the short answer is no. For more recent versions, certainly 5.6 and later, the answer is yes.<br />
<br />
You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. For example:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
=== How can a user process access more than 2 GB of ram in 32-bit Windows? ===<br />
<br />
By default on Windows, the most memory that a user process can access is 2 GB, no matter how much RAM you have installed in your system. With Windows XP Professional you can make it possible for a process to use up to 3 GB of memory by doing two things:<br />
<br />
1) Modify the boot parameters in boot.ini (on my 32 bit WinXP Pro machine, it's in: "C:\boot.ini") to tell the operating system that you want user processes to have access to up to 3GB of RAM (This is a really important file, and if you don't know what you are doing, stop reading this and go back to work!). This is done by adding the /3GB flag to the line of the file that tells the boot loader where the operating system is. My boot.ini file looks like:<br />
<br />
[boot loader]<br />
timeout=30<br />
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS<br />
[operating systems]<br />
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /3GB<br />
<br />
This is a very bad file to make mistakes on, so don't - it may be very difficult to repair your computer to boot if you mess up this file. There is a nice description of this in the Microsoft article <br />
[http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx Memory Support and Windows Operating Systems].<br />
<br />
2) The other thing that you need to do is make your executable LARGEADDRESSAWARE. Assuming that you have a Windows binary that you want to try this on, you can use the 'editbin' utility that comes with Visual Studio to change the setting of one bit (the IMAGE_FILE_LARGE_ADDRESS_AWARE bit) in the image header of the executable. For a program 'prog.exe' you can make the change by<br />
<br />
editbin /LARGEADDRESSAWARE prog.exe<br />
<br />
Of course, depending on how your program handles memory you might find that it crashes when you try to use the extra memory, but that's a separate issue. If you are compiling your program with a version of Visual Studio you should be able to find the switch to make your program /LARGEADDRESSAWARE.<br />
<br />
=== Shared builds of VTK and debugging QVTKWidget using Visual Studio ===<br />
<br />
Assuming that you have built a shared build of VTK and you may or may<br />
not have a set it up such that there is a path to the release version<br />
of VTK in your PATH statement.<br />
<br />
Then if you debug a project that is using QVTKWidget, you will come<br />
across a problem in that if you are debugging a debug version; the<br />
application depends upon the debug version of QVTK.dll which will<br />
depend upon QtGui4d.dll (among others) and load it. But, because the<br />
release version of QVTK.dll is in the path, QtGiu4.dll will also be<br />
loaded preventing the application from running. You will get a<br />
"QWidget: Must construct a QApplication before a QPaintDevice"<br />
message.<br />
<br />
The solution to this problem is to set the path to the correct build<br />
of VTK on the "'''Debugging'''" properties of your project. Right click on<br />
your project, bring up the properties dialog, and select "'''Debugging'''"<br />
from the list on the left. There should be an "'''Environment'''" line. You<br />
can add variables here using key=value pairs.<br />
For example, add the following line:<br />
PATH=<Path To VTK>\bin\$(OutDir);%PATH%<br />
You can then add the same line to other configurations, such as the release one, by selecting<br />
them from the top left drop down box labelled '''Configuration'''.<br />
<br />
$(OutDir) will be set by Visual Studio to either Debug or Release,<br />
depending upon what configuration you have selected. Make sure <br />
that ;%PATH% is appended so that Qt and other files can be appended <br />
to the PATH statement.<br />
<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes in VTK between 3.2 and 4.0 ===<br />
<br />
* 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.<br />
<br />
* 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<br />
<br />
* Added special methods to data arrays to replace methods like<br />
<br />
tc SetTCoord i x y 0<br />
<br />
or<br />
<br />
vc SetVector i vx vy vz<br />
<br />
in interpreted languages (Tcl, Python, Java). Use:<br />
<br />
tc SetTuple2 i x y<br />
<br />
or<br />
<br />
vc SetTuple3 i vx vy vz<br />
<br />
* 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.<br />
<br />
* vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.<br />
<br />
* 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.<br />
<br />
* 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).<br />
<br />
* The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.<br />
<br />
* Support for reading and writing PGM and JPEG images has been included.<br />
<br />
* 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.<br />
<br />
* 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 Imaging 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.<br />
<br />
* 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.<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* 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.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* 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.<br />
<br />
* 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:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== How do I upgrade my existing C++ code from 3.2 to 4.x? ===<br />
<br />
This is (a corrected version of) an email that was posted to vtkusers.<br />
Please feel free to correct or add anything.<br />
<br />
{| cellspacing="3" <br />
|- valign="top"<br />
|width="55%" bgcolor="#f0f0ff" style="border:1px solid #ffc9c9;padding:1em;padding-top:0.5em;"|<br />
<br />
I've just ported my medium-sized (40K lines) application from vtk3.2 to<br />
vtk4.x. I thought I would share my experiences with you, in case there<br />
were people out there contemplating it but a bit scared.<br />
<br />
One source of information for upgrading code is:<br />
<br />
http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the<br />
script in the zip file.<br />
<br />
So,<br />
<br />
I switched all my include directories to the new VTK ones and<br />
recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and<br />
vtkTCoords which have both been removed. Where I was using single value<br />
scalars, like this:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetNumberOfScalars(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetScalar(i,2.3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *scalars = vtkFloatArray::New();<br />
scalars->SetNumberOfComponents(1);<br />
scalars->SetNumberOfTuples(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetTuple1(i,2.3);<br />
...<br />
<br />
OK so far, far fewer errors.<br />
<br />
Where I had 2D texture coordinates:<br />
<br />
vtkTCoords *tcoords = vtkTCoords::New();<br />
tcoords->SetNumberOfTCoords(N);<br />
...<br />
float p[3];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTCoord(i,p);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *tcoords = vtkFloatArray::New();<br />
tcoords->SetNumberOfComponents(2);<br />
tcoords->SetNumberOfTuples(N);<br />
...<br />
float p[2];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTuple(i,p);<br />
....<br />
<br />
All well and good, still fewer errors. Make sure you call<br />
SetNumberOfComponents *before* SetNumberOfTuples else you'll get<br />
problems (I did!).<br />
<br />
Where I was creating 0-255 image data and had been using:<br />
<br />
vtkScalars* scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
...<br />
<br />
Going well!<br />
<br />
When creating RGB images, I had been using:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfScalars(X*Y);<br />
...<br />
scalars->SetActiveComponent(0);<br />
scalars->SetScalar(i,val1);<br />
scalars->SetActiveComponent(1);<br />
scalars->SetScalar(i,val2);<br />
scalars->SetActiveComponent(2);<br />
scalars->SetScalar(i,val3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfTuples(X*Y);<br />
...<br />
scalars->SetComponent(i,0,val1);<br />
scalars->SetComponent(i,1,val2);<br />
scalars->SetComponent(i,2,val3);<br />
...<br />
<br />
My remaining errors concerned vtkWin32OffscreenRenderWindow that has<br />
been removed. Where I had been using:<br />
<br />
vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New();<br />
offscreen->SetOffScreenRendering(1);<br />
...<br />
<br />
All done. I'd had to throw in some #include "vtkFloatArray.h" and things<br />
like that of course. Zero compile errors.<br />
<br />
Had to remember to link against the new vtk lib files, so I removed<br />
<br />
vtkdll.lib <br />
<br />
and added<br />
<br />
vtkCommon.lib<br />
vtkGraphics.lib<br />
<br />
etc.<br />
<br />
Zero link errors. My program is up and running again, no apparant<br />
problems. Plus now I can use all the new features of vtk4. (And I'm sure<br />
it's faster but maybe that's my imagination.)<br />
<br />
All this took me about three hours.<br />
<br />
Bye!<br />
<br />
Tim.<br />
|}<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was releaseed in February 2003. VTK 4.4 (which was an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, 5.0.3 in March 2007, and 5.0.4 in January 2008.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# 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.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* 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.<br />
#* 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.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* 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.<br />
* 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).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* 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. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* 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.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
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.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== Using Volume Rendering in VTK ===<br />
<br />
I recently updated my VTK CVS version. And my c++ code that use to work fine are now complaining about:<br />
<br />
undefined reference to `vtkUnstructuredGridAlgorithm::SetInput(vtkDataObject*)'<br />
undefined reference to `vtkUnstructuredGridAlgorithm::GetOutput()' <br />
<br />
There is now a new subfolder and a new option to enable building the VolumeRendering library. You have to turn VTK_USE_VOLUMERENDERING to ON in order to use it. Also make sure that your executable is linking properly to this new library:<br />
<br />
ADD_EXECUTABLE(foo foo.cxx)<br />
TARGET_LINK_LIBRARIES(foo vtkVolumeRendering)<br />
<br />
=== API Changes in VTK 5.2 ===<br />
<br />
==== <tt>vtkProp::RenderTranslucentGeometry()</tt> is gone ====<br />
<br />
<tt>vtkProp::RenderTranslucentGeometry()</tt> is gone and has been broken down into 3 methods:<br />
* <tt>HasTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderVolumetricGeometry()</tt><br />
<br />
Here is what to change in a vtkProp subclass:<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry only, override <tt>HasTranslucentPolygonalGeometry()</tt> and <tt>RenderTranslucentPolygonalGeometry()</tt>. <b>Just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderTranslucentPolygonalGeometry()</tt> is not enough!</b><br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent volumetric geometry only, override <tt>RenderVolumetricGeometry()</tt>. In this case, just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderVolumetricGeometry()</tt> is OK.<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry and translucent volumetric geometry, override all 3 methods.<br />
<br />
The reason of this change is that <tt>HasTranslucentPolygonalGeometry()</tt> is used to decide if an expensive initialization of the new rendering algorithm of translucent polygonal geometry (depth peeling) is necessary. <tt>RenderTranslucentPolygonalGeometry()</tt> is called multiple times during the rendering of the translucent polygonal geometry of the scene. <tt>RenderVolumetricGeometry()</tt> is called in an additional pass, after depth peeling. For this reason, <b><tt>RenderTranslucentGeometry()</tt> cannot just be marked as deprecated but had to be removed from the API</b>.<br />
<br />
<br />
<br />
==== <tt>vtkImagePlaneWidget</tt> has action names changed ====<br />
from:<br />
enum<br />
{<br />
CURSOR_ACTION = 0,<br />
SLICE_MOTION_ACTION = 1,<br />
WINDOW_LEVEL_ACTION = 2<br />
};<br />
to:<br />
enum<br />
{<br />
VTK_CURSOR_ACTION = 0,<br />
VTK_SLICE_MOTION_ACTION = 1,<br />
VTK_WINDOW_LEVEL_ACTION = 2<br />
};<br />
<br />
==== <tt>GetOutput()</tt> now returns <tt>vtkDataObject</tt> for some algorithms ====<br />
<br />
The following algorithms now work on <tt>vtkGraph</tt> as well as <tt>vtkDataSet</tt>, so no <tt>GetOutput()</tt> longer returns <tt>vtkDataSet</tt>. To obtain the dataset, use <tt>vtkDataSet::SafeDownCast(filter->GetOutput())</tt><br />
* <tt>vtkArrayCalculator</tt><br />
* <tt>vtkAssignAttribute</tt><br />
* <tt>vtkProgrammableFilter</tt><br />
<br />
=== API Changes in VTK 5.4 ===<br />
* empty right now.<br />
=== API Changes in VTK 5.5 ===<br />
<br />
* vtkStreamTracer<br />
Changed<br />
enum Units <br />
{ <br />
TIME_UNIT, <br />
LENGTH_UNIT, <br />
CELL_LENGTH_UNIT <br />
}<br />
to<br />
enum Units<br />
{ <br />
LENGTH_UNIT = 1, <br />
CELL_LENGTH_UNIT = 2 <br />
}<br />
<br />
<br />
Changed<br />
* OUT_OF_TIME = 4<br />
to<br />
* OUT_OF_LENGTH = 4<br />
in enum ''ReasonForTermination''<br />
<br />
<br />
Changed<br />
* LastUsedTimeStep<br />
to<br />
* LastUsedStepSize<br />
<br />
<br />
Changed<br />
* MaximumPropagation<br />
* MaximumIntegrationStep<br />
* MinimumIntegrationStep<br />
* InitialIntegrationStep <br />
from type ''IntervalInformation'' to type ''double''.<br />
<br />
<br />
Added a member variable to the class<br />
* int IntegrationStepUnit<br />
<br />
<br />
The following APIs were '''removed''' from the class:<br />
* void SetMaximumProgration(int unit, double max)<br />
* void SetMaximumProgrationUnit(int unit)<br />
* int GetMaximumPropagationUnit()<br />
* void SetMaximumPropagationUnitToTimeUnit()<br />
* void SetMaximumPropagationUnitToLengthUnit()<br />
* void SetMaximumPropagationUnitToCellLengthUnit()<br />
* void SetMinimumIntegrationStep(int unit, double step)<br />
* void SetMinimumIntegrationStepUnit(int unit)<br />
* int GetMinimumIntegrationStepUnit()<br />
* void SetMinimumIntegrationStepUnitToTimeUnit()<br />
* void SetMinimumIntegrationStepUnitToLengthUnit()<br />
* void SetMinimumIntegrationStepUnitToCellLengthUnit()<br />
* void SetMaximumIntegrationStep(int unit, double step)<br />
* void SetMaximumIntegrationStepUnit(int unit)<br />
* int GetMaximumIntegrationStepUnit()<br />
* void SetMaximumIntegrationStepUnitToTimeUnit()<br />
* void SetMaximumIntegrationStepUnitToLengthUnit()<br />
* void SetMaximumIntegrationStepUnitToCellLengthUnit()<br />
* void SetInitialIntegrationStep(int unit, double step)<br />
* void SetInitialIntegrationStepUnit(int unit)<br />
* int GetInitialIntegrationStepUnit()<br />
* void SetInitialIntegrationStepUnitToTimeUnit()<br />
* void SetInitialIntegrationStepUnitToLengthUnit()<br />
* void SetInitialIntegrationStepUnitToCellLengthUnit()<br />
* void SetIntervalInformation(int unit, double interval, IntervalInformation& currentValues)<br />
* void SetIntervalInformation(int unit,IntervalInformation& currentValues)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength, double speed)<br />
* static double ConvertToTime(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToCellLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToUnit(IntervalInformation& interval, int unit, double cellLength, double speed)<br />
<br />
<br />
The following APIs were added to the class:<br />
* int GetIntegrationStepUnit()<br />
* void SetIntegrationStepUnit(int unit)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength)<br />
* static double ConvertToLength(double interval, int unit, double cellLength)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength)<br />
<br />
<br />
* vtkInterpolatedVelocityField<br />
Added a new member variable and two associated functions:<br />
* bool NormalizeVector<br />
* vtkSetMacro(NormalizeVector, bool)<br />
* vtkGetMacro(NormalizeVector, bool)<br />
<br />
== OpenGL requirements ==<br />
<br />
=== Terminology ===<br />
<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
<br />
==== Linux/Unix ====<br />
<br />
Two ways:<br />
<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
<br />
* vendor specific tool<br />
<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
=== VTK 5.2 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.2? ====<br />
<br />
Same answer than for VTK 5.0.<br />
<br />
==== What is the minimal OpenGL version required by VTK5.2 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>, <tt>vtkHAVSVolumeMapper</tt>,<br />
<tt>vtkGLSLShaderProgram</tt>, depth peeling and some hardware offscreen rendering using framebuffer objects (FBO).<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
If you want to use <tt>vtkHAVSVolumeMapper</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_draw_buffers</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_program</tt><br />
* <tt>GL_ARB_vertex_program</tt><br />
* <tt>GL_EXT_framebuffer_object</tt><br />
* either <tt>GL_ARB_texture_float</tt> or <tt>GL_ATI_texture_float</tt><br />
<br />
The following extension or OpenGL version is used by <tt>vtkHAVSVolumeMapper</tt> if provided (at runtime), but it is optional:<br />
* <tt>GL_ARB_vertex_buffer_object</tt> or OpenGL>=1.5<br />
<br />
If you want to use <tt>vtkGLSLShaderProgram</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_shading_language_100</tt> or OpenGL>=2.0,<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0.<br />
<br />
Depth peeling ( see [[VTK/Depth_Peeling | VTK Depth Peeling]] for more information) requires (at runtime):<br />
* <tt>GL_ARB_depth_texture</tt> or OpenGL>=1.4<br />
* <tt>GL_ARB_shadow</tt> or OpenGL>=1.4<br />
* <tt>GL_EXT_shadow_funcs</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_occlusion_query</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
* <tt>GL_SGIS_texture_edge_clamp</tt> or <tt>GL_EXT_texture_edge_clamp</tt> or OpenGL>=1.2<br />
<br />
Hardware-based offscreen rendering using framebuffer object (FBO) will be used as the default offscreen method if the following extensions or OpenGL version are available (at runtime):<br />
* <tt>GL_EXT_framebuffer_object</tt><br />
and either <br />
* <tt>GL_ARB_texture_non_power_of_two</tt> or OpenGL>=2.0<br />
or<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
In addition, if the the framebuffer needs a stencil buffer, extension <tt>GL_EXT_packed_depth_stencil</tt> is required. Even if all those extensions are supported, the chosen FBO format might<br />
not be supported by the card; in this case, this method of offscreen rendering is not used.<br />
<br />
== Miscellaneous questions ==<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
== Legal issues ==<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Development]]<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. We think it's pretty reasonable. We do restrict the<br />
distribution of modified code. This is primarily a revision control<br />
issue. We don't want a bunch of renegade vtks running around without us<br />
having some idea why the changes were made and giving us a chance to<br />
incorporate them into the general release.<br />
<br />
The text of the VTK copyright is available [http://www.vtk.org/copyright.php here].<br />
<br />
=== What is the deal with the patents ===<br />
<br />
As the copyright mentions there are some patents used in VTK. If you use<br />
any code in the Patented/ directory for commercial application you<br />
should contact the patent holder and obtain a license.<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by General Electric Company: vtkDecimate, vtkMarchingCubes,<br />
vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface.<br />
The GE contact is:<br />
<br />
Carl B. Horton<br />
Sr. Counsel, Intellectual Property<br />
3000 N. Grandview Blvd., W-710<br />
Waukesha, WI 53188<br />
Phone: (262) 513-4022<br />
E-Mail: mailto:Carl.Horton@med.ge.com<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by Kitware, Inc.: vtkGridSynchronizedTemplates3D,<br />
vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and<br />
vtkSynchronizedTemplates3D. The Kitware contact is:<br />
<br />
Ken Martin<br />
Kitware<br />
28 Corporate Drive, Suite 204,<br />
Clifton Park, NY 12065<br />
Phone:1-518-371-3971<br />
E-Mail: mailto:kitware@kitware.com<br />
<br />
=== Can VTK be used as part of a project distributed under a GPL License ? ===<br />
<br />
==== Short Answer ====<br />
<br />
Yes, it is fine to take VTK code and to include it in a project that is distributed under a GPL license.<br />
<br />
==== Long Answer ====<br />
<br />
===== Terms =====<br />
<br />
Let's call project X the larger project that:<br />
<br />
# Will include source code from VTK (in part or as a whole)<br />
# Will be distributed under GPL license<br />
<br />
Note in particular that:<br />
<br />
# The copyright notices in VTK files must be kept.<br />
# If VTK files are modified by the developers of project X, that fact must be clearly indicated.<br />
# Only the modifications of VTK files made by the developers of project X will be covered by a GPL license. The original VTK code remains covered by the VTK license.<br />
# The collection of copyrighted works (project X in this case), that includes VTK (in part or as a whole) and their software will be covered by a GPL license.<br />
<br />
===== Details =====<br />
<br />
As the [http://www.vtk.org/copyright.php VTK license] is a variation of the [http://www.opensource.org/licenses/bsd-license.php Modified BSD license], to which only the following term has been added:<br />
<br />
Modified source versions must be plainly marked as such, <br />
and must not be misrepresented as being the original software.<br />
<br />
and that the Modified BSD license is itself compatible with the GPL <br />
<br />
http://www.gnu.org/philosophy/license-list.html (Modified BSD license)<br />
<br />
Then the VTK license is also compatible with the GPL license. Since the terms of the GPL license do not preclude the additional term of the VTK license from being followed.<br />
<br />
NOTE: The licenses are only '''one way compatible'''.<br />
<br />
* You can use VTK code inside a GPL licensed project.<br />
* You '''can not''' use GPL licensed code inside VTK.<br />
<br />
That is the reason why there are no GPL third party libraries in VTK. Having GPL third party libraries in VTK would prevent closed source projects from being built against VTK.<br />
<br />
== Common problems and their solutions ==<br />
* There are some problems may that arise while building VTK that have very straight forward solutions. [[VTK/BuildingProblems|Here]] they are.<br />
* There are some problems that arise frequently that have very straight forward solutions. [[VTK/CommonProblems|Here]] they are.<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=53235VTK/FAQ2013-07-22T15:11:36Z<p>Seanmcbride: /* Can VTK be built as a Universal Binary on Mac OS X? */</p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk is 5.4.0 (released on 2009-3-26). This release for download available from:<br />
<br />
http://www.vtk.org/VTK/resources/software.html<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesisitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Can I contribute money? ===<br />
<br />
Please don't send money. Not that we think you're going to send in<br />
unsolicited money. But if you were thinking about it, stop. It would<br />
just complicate our lives and make for all sorts of tax problems.<br />
<br />
(Note: if you are a company or funding institution, and would like to fund<br />
features or development, please contact Kitware http://www.kitware.com .)<br />
<br />
=== Is there a mailing list or Usenet newsgroup for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
There is also a newsgroup that mirrors the mailinglist. At this point it<br />
seems that mirror is down. Mail to the mailinglist used to be posted the<br />
newsgroup, but posts on the newsgroup were not sent to the mailinglist.<br />
The newsgroup was located at:<br />
news://scully.esat.kuleuven.ac.be/vtk.mailinglist<br />
<br />
http://www.gmane.org is a bidirectional mail-to-news gateway that carries the vtkusers mailing list. Its located here: news://news.gmane.org/gmane.comp.lib.vtk.user or here: http://news.gmane.org/gmane.comp.lib.vtk.user. vtkusers mails have been archived since April 2002 and they never expire. You can read and send mails to the vtkusers list but sent mail will bounce back without having subscribed to the list first.<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://public.kitware.com/dashboard.php?name=vtk<br />
<br />
VTK uses Dart to perform builds, run tests, and generate dashboards. You<br />
can find more information about Dart at: http://public.kitware.com/Dart/<br />
<br />
You can help improve the quality of VTK by supplying the authors with<br />
Tcl scripts that can be used as or turned into regression tests. A good<br />
regression test will:<br />
<br />
# Cover code that is not already covered.<br />
# Illustrate a bug that is occuring now or that has occurred in the past.<br />
# Use data that is on the 2nd Edition book CDROM or use "small" data files or use no data at all.<br />
# Optionally, produce an interesting result. <br />
<br />
Currently almost all regression tests are written in Tcl.<br />
<br />
Please send your Tcl regression tests to:<br />
mailto:wlorens1@mail.nycap.rr.com<br />
<br />
Bill will evaluate them for applicability and integrate them into the<br />
nightly test process.<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are six things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# Check out some of the material at [[VTK Courses, Classes, Presentations]].<br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and [[VTK/Examples|look at the examples]] (there are hundreds). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled [[http://www.catb.org/~esr/faqs/smart-questions.html How to ask questions the smart way]]. [[http://www.mikeash.com/getting_answers.html Getting Answers]] is a good starting point too.<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Avoid HTML emails.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
bacause the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Accessing VTK CVS from behind a firewall ===<br />
<br />
Use the sourceforge project:<br />
<br />
http://cvsgrab.sourceforge.net/<br />
<br />
Just download the script and type something like:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xx<br />
<br />
(Thanks to Ingo H. de Boer)<br />
<br />
Also cvsgrab support the following option to access a particular branch:<br />
<br />
-tag <version tag> [optional] The version tag of the files to download<br />
<br />
For example to get the latest 4.4 branch:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xxx<br />
-tag release-4-4<br />
<br />
=== Where can I obtain test and sample datasets? ===<br />
<br />
See [[VTK Datasets|this page]] for details on downloading datasets that VTK can read.<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# 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.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
* [http://public.kitware.com/pipermail/vtkusers/2003-October/070054.html vtk, Python and SWIG - 'state of the union']<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# 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''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
==== GDCM ====<br />
<br />
For a more elaborate DICOM library that supports more image format, you might try [http://gdcm.sourceforge.net GDCM].<br />
Specifically: [http://gdcm.sourceforge.net/html/classvtkGDCMImageReader.html vtkGDCMImageReader] & [http://gdcm.sourceforge.net/html/classvtkGDCMImageWriter.html vtkGDCMImageWriter]<br />
<br />
Grassroots DiCoM is a C++ library for DICOM medical files. It is automatically wrapped to python/C#/Java (using swig). It supports RAW,JPEG (lossy/lossless),J2K,JPEG-LS,RLE and deflated. It also comes with DICOM Part 3,6 & 7 of the standard as XML files.<br />
<br />
If GDCM is too complex to integrate in your environment you can also consider simply using the command line converter: [http://apps.sourceforge.net/mediawiki/gdcm/index.php?title=Gdcmconv gdcmconv] to convert an unsupported DICOM file into something that vtkDICOMImageReader, can support. Typically you would want:<br />
<br />
gdcmconv --raw compressed_input.dcom uncompressed_output.dcom<br />
<br />
==== dicom2 ====<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== vtkVolume16Reader ====<br />
<br />
When searching the vtkusers mailing list a lot of posts are still using vtkVolume16Reader to read in DICOM file. It will works in the following case:<br />
* You know the dimension (cols & rows) of your image<br />
* You know the spacing of your image<br />
* You know the pixel type (pixel type & #components) of your image<br />
* You know Pixel Data (7fe0,0010) is the last element in the image<br />
* You know Pixel Data (7fe0,0010) was sent in uncompressed format (not encapsulated)<br />
<br />
All those requirements are a stronger set of requirements than vtkDICOMImageReader, therefore it is encourage to use vtkDICOMImageReader instead.<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
GDCM 1.x:<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
GDCM 2.x:<br />
IPPSorter ipp;<br />
ipp.Sort( filenames );<br />
zspacing = ipp.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
==== Using ReleaseDataFlag ====<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
==== Use ImmediateModeRendering ====<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
==== Use triangle strips via vtkStripper. ====<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
==== Use a different filter or mapper ====<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use the STL.<br />
However, see the [[VTK Coding Standards]] for limitations.<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
==== Vim indentation ====<br />
<br />
[[user talk:Andy|Andy Cedilnik]] has some information on following the VTK coding guidelines using vim. You may place the following in your <code>~/.vimrc</code> file<br />
set tabstop=2 " Tabs are two characters<br />
set shiftwidth=2 " Indents are two charactes too<br />
set expandtab " Do not use tabs<br />
set cinoptions={1s,:0,l1,g0,c0,(0,(s,m1<br />
"Keep tabs in makefiles as they are significant:<br />
:autocmd BufRead,BufNewFile [Mm]akefile :set noexpandtab<br />
<br />
=== How to display transparent objects? ===<br />
(keywords: alpha, correct, depth, geometry, object, opacity, opaque, order, ordering, peel, peeling, sorting, translucent, transparent.)<br />
<br />
When opaque geometry is rendered, there is no need to sort it because the depth buffer (or z-buffer) is used and the sorting is done automatically by keeping the geometry closest to the viewpoint at<br />
a given pixel. (It is easy because it is a MAX/MIN calculation, not a real sorting).<br />
<br />
With translucent geometry the final color of a pixel is the contribution of all the geometry primitives visible through the pixel. The color of the pixel is the result of <b>a</b> blending operation between the colors of all visible primitives. Blending operations themselves are usually order-dependent (ie not commutative). That's why depth sorting is required. There are two ways to fix the ordering in VTK:<br />
<br />
*1. Append all your polygonal geometry with [http://www.vtk.org/doc/nightly/html/classvtkAppendPolyData.html vtkAppendPolyData] and pass it to [http://www.vtk.org/doc/nightly/html/classvtkDepthSortPolyData.html vtkDepthSortPolyData]. See this tcl [http://public.kitware.com/cgi-bin/viewcvs.cgi/*checkout*/Hybrid/Testing/Tcl/depthSort.tcl?root=VTK&content-type=text/plain example]. Depth sorting is done per centroid of geometry primitives, not per pixel. For this reason it is not exact but it solves <b>most</b> of the ordering and gives result usually good enough.<br />
* 2. If the graphics card supports it, use "[[VTK/Depth_Peeling | depth peeling]]". It performs per pixel sorting (better result) but it is really slow.<br />
<br />
=== What's the deal with SetInput() vs. SetInputConnection()? ===<br />
(keywords: SetInput, SetInputConnection, vtkAlgorithm, algorithm, pipeline, source)<br />
<br />
In the transition from VTK 4 to VTK 5, the VTK pipeline executive was completely cleaned up and redesigned. The fundamental idea behind the new pipeline is that the "pipeline" should consist of a chain of "algorithm" objects.<br />
The algorithms are connected together with the familiar b->SetInputConnection(a->GetOutputPort()) methods.<br />
<br />
So how is this different from SetInput()/GetOutput()? The difference between an "OutputPort" and an "Output" is as follows:<br />
<br />
* OutputPort (''vtkAlgorithmOutput''): A trivial object that says "I am output port N of algorithm X" (usually N = 0).<br />
* Output (''subclass of vtkDataObject''): A container for data produced by any VTK code.<br />
<br />
The "OutputPort" method does not presuppose anything about what data (if any) will pass along the pipeline. It could simply signify that algorithm "a" must execute before algorithm "b". This provides enormous flexibility. Trust the VTK designers here, it's better to do things this way than to have the user grab the actual data object from the output of one algorithm and shove it into the input of another.<br />
<br />
However, any newcomer to VTK will quickly notice that the use of SetInputConnection() is not universal. The reason is this: only vtkAlgorithm objects can have a SetInputConnection() or GetOutputPort() method. Some objects that can take inputs are not derived from vtkAlgorithm. For example vtkImageActor is a vtkProp3D and therefore it cannot be a vtkAlgorithm (VTK never uses multiple inheritance). This is a case of an old VTK object that doesn't "fit" the new VTK 5 pipeline. However, the VTK developers did not want to throw away such useful classes when the pipeline was redesigned. Instead, such classes are still served by the backwards-compatible SetInput() method.<br />
<br />
So, use SetInputConnection() whenever you can, but if there is no SetInputConnection(), then go ahead and use SetInput(). There is nothing wrong with doing so. The new pipeline is backwards compatible with the old pipeline methods.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows and Mac workstations.<br />
<br />
=== What Graphics Cards work with VTK ===<br />
<br />
VTK uses OpenGL to perform almost all of its rendering and some graphics cards/drivers have better support for OpenGL than others. This is not a listing of what cards perform well. It is a listing of what cards actually produce correct results. Here is a list of cards and their status roughly in best to worst order.<br />
<br />
* Any Nvidia desktop card on Windows -- 100% compatible<br /> <br />
* Any ATI desktop cards on Windows -- 100% compatible<br /><br />
* Mesa -- most releases pass all VTK tests<br /><br />
* Microsoft Software OpenGL -- passes all VTK tests but does have a couple bugs<br /><br />
* Mac graphics cards -- these usually pass all VTK tests. Older cards may have some issues, for example, the ATI Rage 128 Pro does not support textures larger than 1024x1024.<br /><br />
* Non-linux UNIX cards (Sun HP SGI) -- These generally work<br /><br />
* Any Nvidia card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Any ATI card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Nvidia laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests<br /><br />
* ATI laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests (e.g. [http://public.kitware.com/pipermail/vtkusers/2004-August/075966.html ATI Mobility Radeon 9600])<br /><br />
* Intel Extreme Graphics -- fails some VTK tests<br /><br />
<br />
=== How do I build the examples on the PC running Windows? ===<br />
<br />
Since building the C++ examples on the PC isn't all that easy, here are<br />
some instructions from Jack McInerney.<br />
<br />
Steps for creating a VTK C++ project 8/14/96<br />
<br />
This is based on what I learned creating a project to run the Mace<br />
example. These steps allowed me to successfully built and run this example.<br />
<br />
# Create a console project (File, New, then select Console application).<br />
# Add the files of interest to the project. (e.g., Mace.cxx)<br />
# Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies<br /> 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<br />
# 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).<br />
# 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 <br /> This is a self extracting archive which contains these files. Simply place them in your windows system directory.<br />
# Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless<br /><br />
<br />
When you go to run the program, it will bomb out unless it can find 2<br />
DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the<br />
project directory or the C:\WINDOWS directory. These files are supplied<br />
on the vtk CD-ROM (in the vtk\bin directory).<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
vtk builds on 64 bit systems, that is, systems where sizeof(void*) is 64 bits. However, parts of the vtk codebase are not 64 bit clean and so runtime problems are likely if that code is used.<br />
<br />
===== General =====<br />
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.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5 and later, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work well with 64 bit Cocoa on Mac OS X 10.5 and later.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== What size swap space should I use on a PC? ===<br />
<br />
Building vtk on the PC requires a significant amount of memory (at least<br />
when using Visual C++)... but the final product is nice and compact. To<br />
build vtk on the PC, we recommend setting the min/max swap space to at<br />
least 400MB/500MB (depending on how much RAM you have... the sum of RAM<br />
and swap space should be roughly 500+ MB).<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
See http://paraview.org/Wiki/ParaView_And_Mesa_3D.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
On Mac OS X, there are (at least) two kinds of executables:<br />
* [http://developer.apple.com/documentation/MacOSX/Conceptual/BPInternational/Articles/InternatSupport.html#//apple_ref/doc/uid/20000278-73764 Application Bundles]<br />
* plain UNIX executables<br />
<br />
For a program to be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction) it really should be an Application Bundle. If a plain UNIX executable tries, there will be various bugs, such as keyboard and mouse events not working reliably.<br />
<br />
Many, but not all, of the example VTK applications are built as plain UNIX executables, and thus have these problems. This is [http://www.vtk.org/Bug/bug.php?op=show&bugid=2025 VTK bug 2025].<br />
<br />
When you build your own VTK application, it is best to make it in the form of an Application Bundle. With CMake 2.0.5 or later, simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an Application Bundle (perhaps because your app needs command line parameters) you might be able to avoid the above problems by adding an [http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/ConfigFiles.html#//apple_ref/doc/uid/20002091-SW1 __info_plist section] to your Mach-O executable. If you succeed, please post to the VTK list.<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.4 and older, the short answer is "no". For more recent versions, certainly 5.6 and later, the answer is yes.<br />
<br />
You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. For example:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
=== How can a user process access more than 2 GB of ram in 32-bit Windows? ===<br />
<br />
By default on Windows, the most memory that a user process can access is 2 GB, no matter how much RAM you have installed in your system. With Windows XP Professional you can make it possible for a process to use up to 3 GB of memory by doing two things:<br />
<br />
1) Modify the boot parameters in boot.ini (on my 32 bit WinXP Pro machine, it's in: "C:\boot.ini") to tell the operating system that you want user processes to have access to up to 3GB of RAM (This is a really important file, and if you don't know what you are doing, stop reading this and go back to work!). This is done by adding the /3GB flag to the line of the file that tells the boot loader where the operating system is. My boot.ini file looks like:<br />
<br />
[boot loader]<br />
timeout=30<br />
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS<br />
[operating systems]<br />
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /3GB<br />
<br />
This is a very bad file to make mistakes on, so don't - it may be very difficult to repair your computer to boot if you mess up this file. There is a nice description of this in the Microsoft article <br />
[http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx Memory Support and Windows Operating Systems].<br />
<br />
2) The other thing that you need to do is make your executable LARGEADDRESSAWARE. Assuming that you have a Windows binary that you want to try this on, you can use the 'editbin' utility that comes with Visual Studio to change the setting of one bit (the IMAGE_FILE_LARGE_ADDRESS_AWARE bit) in the image header of the executable. For a program 'prog.exe' you can make the change by<br />
<br />
editbin /LARGEADDRESSAWARE prog.exe<br />
<br />
Of course, depending on how your program handles memory you might find that it crashes when you try to use the extra memory, but that's a separate issue. If you are compiling your program with a version of Visual Studio you should be able to find the switch to make your program /LARGEADDRESSAWARE.<br />
<br />
=== Shared builds of VTK and debugging QVTKWidget using Visual Studio ===<br />
<br />
Assuming that you have built a shared build of VTK and you may or may<br />
not have a set it up such that there is a path to the release version<br />
of VTK in your PATH statement.<br />
<br />
Then if you debug a project that is using QVTKWidget, you will come<br />
across a problem in that if you are debugging a debug version; the<br />
application depends upon the debug version of QVTK.dll which will<br />
depend upon QtGui4d.dll (among others) and load it. But, because the<br />
release version of QVTK.dll is in the path, QtGiu4.dll will also be<br />
loaded preventing the application from running. You will get a<br />
"QWidget: Must construct a QApplication before a QPaintDevice"<br />
message.<br />
<br />
The solution to this problem is to set the path to the correct build<br />
of VTK on the "'''Debugging'''" properties of your project. Right click on<br />
your project, bring up the properties dialog, and select "'''Debugging'''"<br />
from the list on the left. There should be an "'''Environment'''" line. You<br />
can add variables here using key=value pairs.<br />
For example, add the following line:<br />
PATH=<Path To VTK>\bin\$(OutDir);%PATH%<br />
You can then add the same line to other configurations, such as the release one, by selecting<br />
them from the top left drop down box labelled '''Configuration'''.<br />
<br />
$(OutDir) will be set by Visual Studio to either Debug or Release,<br />
depending upon what configuration you have selected. Make sure <br />
that ;%PATH% is appended so that Qt and other files can be appended <br />
to the PATH statement.<br />
<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes in VTK between 3.2 and 4.0 ===<br />
<br />
* 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.<br />
<br />
* 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<br />
<br />
* Added special methods to data arrays to replace methods like<br />
<br />
tc SetTCoord i x y 0<br />
<br />
or<br />
<br />
vc SetVector i vx vy vz<br />
<br />
in interpreted languages (Tcl, Python, Java). Use:<br />
<br />
tc SetTuple2 i x y<br />
<br />
or<br />
<br />
vc SetTuple3 i vx vy vz<br />
<br />
* 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.<br />
<br />
* vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.<br />
<br />
* 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.<br />
<br />
* 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).<br />
<br />
* The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.<br />
<br />
* Support for reading and writing PGM and JPEG images has been included.<br />
<br />
* 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.<br />
<br />
* 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 Imaging 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.<br />
<br />
* 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.<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* 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.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* 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.<br />
<br />
* 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:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== How do I upgrade my existing C++ code from 3.2 to 4.x? ===<br />
<br />
This is (a corrected version of) an email that was posted to vtkusers.<br />
Please feel free to correct or add anything.<br />
<br />
{| cellspacing="3" <br />
|- valign="top"<br />
|width="55%" bgcolor="#f0f0ff" style="border:1px solid #ffc9c9;padding:1em;padding-top:0.5em;"|<br />
<br />
I've just ported my medium-sized (40K lines) application from vtk3.2 to<br />
vtk4.x. I thought I would share my experiences with you, in case there<br />
were people out there contemplating it but a bit scared.<br />
<br />
One source of information for upgrading code is:<br />
<br />
http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the<br />
script in the zip file.<br />
<br />
So,<br />
<br />
I switched all my include directories to the new VTK ones and<br />
recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and<br />
vtkTCoords which have both been removed. Where I was using single value<br />
scalars, like this:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetNumberOfScalars(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetScalar(i,2.3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *scalars = vtkFloatArray::New();<br />
scalars->SetNumberOfComponents(1);<br />
scalars->SetNumberOfTuples(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetTuple1(i,2.3);<br />
...<br />
<br />
OK so far, far fewer errors.<br />
<br />
Where I had 2D texture coordinates:<br />
<br />
vtkTCoords *tcoords = vtkTCoords::New();<br />
tcoords->SetNumberOfTCoords(N);<br />
...<br />
float p[3];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTCoord(i,p);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *tcoords = vtkFloatArray::New();<br />
tcoords->SetNumberOfComponents(2);<br />
tcoords->SetNumberOfTuples(N);<br />
...<br />
float p[2];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTuple(i,p);<br />
....<br />
<br />
All well and good, still fewer errors. Make sure you call<br />
SetNumberOfComponents *before* SetNumberOfTuples else you'll get<br />
problems (I did!).<br />
<br />
Where I was creating 0-255 image data and had been using:<br />
<br />
vtkScalars* scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
...<br />
<br />
Going well!<br />
<br />
When creating RGB images, I had been using:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfScalars(X*Y);<br />
...<br />
scalars->SetActiveComponent(0);<br />
scalars->SetScalar(i,val1);<br />
scalars->SetActiveComponent(1);<br />
scalars->SetScalar(i,val2);<br />
scalars->SetActiveComponent(2);<br />
scalars->SetScalar(i,val3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfTuples(X*Y);<br />
...<br />
scalars->SetComponent(i,0,val1);<br />
scalars->SetComponent(i,1,val2);<br />
scalars->SetComponent(i,2,val3);<br />
...<br />
<br />
My remaining errors concerned vtkWin32OffscreenRenderWindow that has<br />
been removed. Where I had been using:<br />
<br />
vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New();<br />
offscreen->SetOffScreenRendering(1);<br />
...<br />
<br />
All done. I'd had to throw in some #include "vtkFloatArray.h" and things<br />
like that of course. Zero compile errors.<br />
<br />
Had to remember to link against the new vtk lib files, so I removed<br />
<br />
vtkdll.lib <br />
<br />
and added<br />
<br />
vtkCommon.lib<br />
vtkGraphics.lib<br />
<br />
etc.<br />
<br />
Zero link errors. My program is up and running again, no apparant<br />
problems. Plus now I can use all the new features of vtk4. (And I'm sure<br />
it's faster but maybe that's my imagination.)<br />
<br />
All this took me about three hours.<br />
<br />
Bye!<br />
<br />
Tim.<br />
|}<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was releaseed in February 2003. VTK 4.4 (which was an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, 5.0.3 in March 2007, and 5.0.4 in January 2008.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# 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.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* 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.<br />
#* 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.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* 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.<br />
* 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).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* 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. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* 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.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
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.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== Using Volume Rendering in VTK ===<br />
<br />
I recently updated my VTK CVS version. And my c++ code that use to work fine are now complaining about:<br />
<br />
undefined reference to `vtkUnstructuredGridAlgorithm::SetInput(vtkDataObject*)'<br />
undefined reference to `vtkUnstructuredGridAlgorithm::GetOutput()' <br />
<br />
There is now a new subfolder and a new option to enable building the VolumeRendering library. You have to turn VTK_USE_VOLUMERENDERING to ON in order to use it. Also make sure that your executable is linking properly to this new library:<br />
<br />
ADD_EXECUTABLE(foo foo.cxx)<br />
TARGET_LINK_LIBRARIES(foo vtkVolumeRendering)<br />
<br />
=== API Changes in VTK 5.2 ===<br />
<br />
==== <tt>vtkProp::RenderTranslucentGeometry()</tt> is gone ====<br />
<br />
<tt>vtkProp::RenderTranslucentGeometry()</tt> is gone and has been broken down into 3 methods:<br />
* <tt>HasTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderVolumetricGeometry()</tt><br />
<br />
Here is what to change in a vtkProp subclass:<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry only, override <tt>HasTranslucentPolygonalGeometry()</tt> and <tt>RenderTranslucentPolygonalGeometry()</tt>. <b>Just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderTranslucentPolygonalGeometry()</tt> is not enough!</b><br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent volumetric geometry only, override <tt>RenderVolumetricGeometry()</tt>. In this case, just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderVolumetricGeometry()</tt> is OK.<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry and translucent volumetric geometry, override all 3 methods.<br />
<br />
The reason of this change is that <tt>HasTranslucentPolygonalGeometry()</tt> is used to decide if an expensive initialization of the new rendering algorithm of translucent polygonal geometry (depth peeling) is necessary. <tt>RenderTranslucentPolygonalGeometry()</tt> is called multiple times during the rendering of the translucent polygonal geometry of the scene. <tt>RenderVolumetricGeometry()</tt> is called in an additional pass, after depth peeling. For this reason, <b><tt>RenderTranslucentGeometry()</tt> cannot just be marked as deprecated but had to be removed from the API</b>.<br />
<br />
<br />
<br />
==== <tt>vtkImagePlaneWidget</tt> has action names changed ====<br />
from:<br />
enum<br />
{<br />
CURSOR_ACTION = 0,<br />
SLICE_MOTION_ACTION = 1,<br />
WINDOW_LEVEL_ACTION = 2<br />
};<br />
to:<br />
enum<br />
{<br />
VTK_CURSOR_ACTION = 0,<br />
VTK_SLICE_MOTION_ACTION = 1,<br />
VTK_WINDOW_LEVEL_ACTION = 2<br />
};<br />
<br />
==== <tt>GetOutput()</tt> now returns <tt>vtkDataObject</tt> for some algorithms ====<br />
<br />
The following algorithms now work on <tt>vtkGraph</tt> as well as <tt>vtkDataSet</tt>, so no <tt>GetOutput()</tt> longer returns <tt>vtkDataSet</tt>. To obtain the dataset, use <tt>vtkDataSet::SafeDownCast(filter->GetOutput())</tt><br />
* <tt>vtkArrayCalculator</tt><br />
* <tt>vtkAssignAttribute</tt><br />
* <tt>vtkProgrammableFilter</tt><br />
<br />
=== API Changes in VTK 5.4 ===<br />
* empty right now.<br />
=== API Changes in VTK 5.5 ===<br />
<br />
* vtkStreamTracer<br />
Changed<br />
enum Units <br />
{ <br />
TIME_UNIT, <br />
LENGTH_UNIT, <br />
CELL_LENGTH_UNIT <br />
}<br />
to<br />
enum Units<br />
{ <br />
LENGTH_UNIT = 1, <br />
CELL_LENGTH_UNIT = 2 <br />
}<br />
<br />
<br />
Changed<br />
* OUT_OF_TIME = 4<br />
to<br />
* OUT_OF_LENGTH = 4<br />
in enum ''ReasonForTermination''<br />
<br />
<br />
Changed<br />
* LastUsedTimeStep<br />
to<br />
* LastUsedStepSize<br />
<br />
<br />
Changed<br />
* MaximumPropagation<br />
* MaximumIntegrationStep<br />
* MinimumIntegrationStep<br />
* InitialIntegrationStep <br />
from type ''IntervalInformation'' to type ''double''.<br />
<br />
<br />
Added a member variable to the class<br />
* int IntegrationStepUnit<br />
<br />
<br />
The following APIs were '''removed''' from the class:<br />
* void SetMaximumProgration(int unit, double max)<br />
* void SetMaximumProgrationUnit(int unit)<br />
* int GetMaximumPropagationUnit()<br />
* void SetMaximumPropagationUnitToTimeUnit()<br />
* void SetMaximumPropagationUnitToLengthUnit()<br />
* void SetMaximumPropagationUnitToCellLengthUnit()<br />
* void SetMinimumIntegrationStep(int unit, double step)<br />
* void SetMinimumIntegrationStepUnit(int unit)<br />
* int GetMinimumIntegrationStepUnit()<br />
* void SetMinimumIntegrationStepUnitToTimeUnit()<br />
* void SetMinimumIntegrationStepUnitToLengthUnit()<br />
* void SetMinimumIntegrationStepUnitToCellLengthUnit()<br />
* void SetMaximumIntegrationStep(int unit, double step)<br />
* void SetMaximumIntegrationStepUnit(int unit)<br />
* int GetMaximumIntegrationStepUnit()<br />
* void SetMaximumIntegrationStepUnitToTimeUnit()<br />
* void SetMaximumIntegrationStepUnitToLengthUnit()<br />
* void SetMaximumIntegrationStepUnitToCellLengthUnit()<br />
* void SetInitialIntegrationStep(int unit, double step)<br />
* void SetInitialIntegrationStepUnit(int unit)<br />
* int GetInitialIntegrationStepUnit()<br />
* void SetInitialIntegrationStepUnitToTimeUnit()<br />
* void SetInitialIntegrationStepUnitToLengthUnit()<br />
* void SetInitialIntegrationStepUnitToCellLengthUnit()<br />
* void SetIntervalInformation(int unit, double interval, IntervalInformation& currentValues)<br />
* void SetIntervalInformation(int unit,IntervalInformation& currentValues)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength, double speed)<br />
* static double ConvertToTime(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToCellLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToUnit(IntervalInformation& interval, int unit, double cellLength, double speed)<br />
<br />
<br />
The following APIs were added to the class:<br />
* int GetIntegrationStepUnit()<br />
* void SetIntegrationStepUnit(int unit)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength)<br />
* static double ConvertToLength(double interval, int unit, double cellLength)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength)<br />
<br />
<br />
* vtkInterpolatedVelocityField<br />
Added a new member variable and two associated functions:<br />
* bool NormalizeVector<br />
* vtkSetMacro(NormalizeVector, bool)<br />
* vtkGetMacro(NormalizeVector, bool)<br />
<br />
== OpenGL requirements ==<br />
<br />
=== Terminology ===<br />
<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
<br />
==== Linux/Unix ====<br />
<br />
Two ways:<br />
<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
<br />
* vendor specific tool<br />
<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
=== VTK 5.2 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.2? ====<br />
<br />
Same answer than for VTK 5.0.<br />
<br />
==== What is the minimal OpenGL version required by VTK5.2 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>, <tt>vtkHAVSVolumeMapper</tt>,<br />
<tt>vtkGLSLShaderProgram</tt>, depth peeling and some hardware offscreen rendering using framebuffer objects (FBO).<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
If you want to use <tt>vtkHAVSVolumeMapper</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_draw_buffers</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_program</tt><br />
* <tt>GL_ARB_vertex_program</tt><br />
* <tt>GL_EXT_framebuffer_object</tt><br />
* either <tt>GL_ARB_texture_float</tt> or <tt>GL_ATI_texture_float</tt><br />
<br />
The following extension or OpenGL version is used by <tt>vtkHAVSVolumeMapper</tt> if provided (at runtime), but it is optional:<br />
* <tt>GL_ARB_vertex_buffer_object</tt> or OpenGL>=1.5<br />
<br />
If you want to use <tt>vtkGLSLShaderProgram</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_shading_language_100</tt> or OpenGL>=2.0,<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0.<br />
<br />
Depth peeling ( see [[VTK/Depth_Peeling | VTK Depth Peeling]] for more information) requires (at runtime):<br />
* <tt>GL_ARB_depth_texture</tt> or OpenGL>=1.4<br />
* <tt>GL_ARB_shadow</tt> or OpenGL>=1.4<br />
* <tt>GL_EXT_shadow_funcs</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_occlusion_query</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
* <tt>GL_SGIS_texture_edge_clamp</tt> or <tt>GL_EXT_texture_edge_clamp</tt> or OpenGL>=1.2<br />
<br />
Hardware-based offscreen rendering using framebuffer object (FBO) will be used as the default offscreen method if the following extensions or OpenGL version are available (at runtime):<br />
* <tt>GL_EXT_framebuffer_object</tt><br />
and either <br />
* <tt>GL_ARB_texture_non_power_of_two</tt> or OpenGL>=2.0<br />
or<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
In addition, if the the framebuffer needs a stencil buffer, extension <tt>GL_EXT_packed_depth_stencil</tt> is required. Even if all those extensions are supported, the chosen FBO format might<br />
not be supported by the card; in this case, this method of offscreen rendering is not used.<br />
<br />
== Miscellaneous questions ==<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
== Legal issues ==<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Development]]<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. We think it's pretty reasonable. We do restrict the<br />
distribution of modified code. This is primarily a revision control<br />
issue. We don't want a bunch of renegade vtks running around without us<br />
having some idea why the changes were made and giving us a chance to<br />
incorporate them into the general release.<br />
<br />
The text of the VTK copyright is available [http://www.vtk.org/copyright.php here].<br />
<br />
=== What is the deal with the patents ===<br />
<br />
As the copyright mentions there are some patents used in VTK. If you use<br />
any code in the Patented/ directory for commercial application you<br />
should contact the patent holder and obtain a license.<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by General Electric Company: vtkDecimate, vtkMarchingCubes,<br />
vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface.<br />
The GE contact is:<br />
<br />
Carl B. Horton<br />
Sr. Counsel, Intellectual Property<br />
3000 N. Grandview Blvd., W-710<br />
Waukesha, WI 53188<br />
Phone: (262) 513-4022<br />
E-Mail: mailto:Carl.Horton@med.ge.com<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by Kitware, Inc.: vtkGridSynchronizedTemplates3D,<br />
vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and<br />
vtkSynchronizedTemplates3D. The Kitware contact is:<br />
<br />
Ken Martin<br />
Kitware<br />
28 Corporate Drive, Suite 204,<br />
Clifton Park, NY 12065<br />
Phone:1-518-371-3971<br />
E-Mail: mailto:kitware@kitware.com<br />
<br />
=== Can VTK be used as part of a project distributed under a GPL License ? ===<br />
<br />
==== Short Answer ====<br />
<br />
Yes, it is fine to take VTK code and to include it in a project that is distributed under a GPL license.<br />
<br />
==== Long Answer ====<br />
<br />
===== Terms =====<br />
<br />
Let's call project X the larger project that:<br />
<br />
# Will include source code from VTK (in part or as a whole)<br />
# Will be distributed under GPL license<br />
<br />
Note in particular that:<br />
<br />
# The copyright notices in VTK files must be kept.<br />
# If VTK files are modified by the developers of project X, that fact must be clearly indicated.<br />
# Only the modifications of VTK files made by the developers of project X will be covered by a GPL license. The original VTK code remains covered by the VTK license.<br />
# The collection of copyrighted works (project X in this case), that includes VTK (in part or as a whole) and their software will be covered by a GPL license.<br />
<br />
===== Details =====<br />
<br />
As the [http://www.vtk.org/copyright.php VTK license] is a variation of the [http://www.opensource.org/licenses/bsd-license.php Modified BSD license], to which only the following term has been added:<br />
<br />
Modified source versions must be plainly marked as such, <br />
and must not be misrepresented as being the original software.<br />
<br />
and that the Modified BSD license is itself compatible with the GPL <br />
<br />
http://www.gnu.org/philosophy/license-list.html (Modified BSD license)<br />
<br />
Then the VTK license is also compatible with the GPL license. Since the terms of the GPL license do not preclude the additional term of the VTK license from being followed.<br />
<br />
NOTE: The licenses are only '''one way compatible'''.<br />
<br />
* You can use VTK code inside a GPL licensed project.<br />
* You '''can not''' use GPL licensed code inside VTK.<br />
<br />
That is the reason why there are no GPL third party libraries in VTK. Having GPL third party libraries in VTK would prevent closed source projects from being built against VTK.<br />
<br />
== Common problems and their solutions ==<br />
* There are some problems may that arise while building VTK that have very straight forward solutions. [[VTK/BuildingProblems|Here]] they are.<br />
* There are some problems that arise frequently that have very straight forward solutions. [[VTK/CommonProblems|Here]] they are.<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=53234VTK/FAQ2013-07-22T15:03:56Z<p>Seanmcbride: /* Mac OS X Specific */</p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk is 5.4.0 (released on 2009-3-26). This release for download available from:<br />
<br />
http://www.vtk.org/VTK/resources/software.html<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesisitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Can I contribute money? ===<br />
<br />
Please don't send money. Not that we think you're going to send in<br />
unsolicited money. But if you were thinking about it, stop. It would<br />
just complicate our lives and make for all sorts of tax problems.<br />
<br />
(Note: if you are a company or funding institution, and would like to fund<br />
features or development, please contact Kitware http://www.kitware.com .)<br />
<br />
=== Is there a mailing list or Usenet newsgroup for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
There is also a newsgroup that mirrors the mailinglist. At this point it<br />
seems that mirror is down. Mail to the mailinglist used to be posted the<br />
newsgroup, but posts on the newsgroup were not sent to the mailinglist.<br />
The newsgroup was located at:<br />
news://scully.esat.kuleuven.ac.be/vtk.mailinglist<br />
<br />
http://www.gmane.org is a bidirectional mail-to-news gateway that carries the vtkusers mailing list. Its located here: news://news.gmane.org/gmane.comp.lib.vtk.user or here: http://news.gmane.org/gmane.comp.lib.vtk.user. vtkusers mails have been archived since April 2002 and they never expire. You can read and send mails to the vtkusers list but sent mail will bounce back without having subscribed to the list first.<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://public.kitware.com/dashboard.php?name=vtk<br />
<br />
VTK uses Dart to perform builds, run tests, and generate dashboards. You<br />
can find more information about Dart at: http://public.kitware.com/Dart/<br />
<br />
You can help improve the quality of VTK by supplying the authors with<br />
Tcl scripts that can be used as or turned into regression tests. A good<br />
regression test will:<br />
<br />
# Cover code that is not already covered.<br />
# Illustrate a bug that is occuring now or that has occurred in the past.<br />
# Use data that is on the 2nd Edition book CDROM or use "small" data files or use no data at all.<br />
# Optionally, produce an interesting result. <br />
<br />
Currently almost all regression tests are written in Tcl.<br />
<br />
Please send your Tcl regression tests to:<br />
mailto:wlorens1@mail.nycap.rr.com<br />
<br />
Bill will evaluate them for applicability and integrate them into the<br />
nightly test process.<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are six things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# Check out some of the material at [[VTK Courses, Classes, Presentations]].<br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and [[VTK/Examples|look at the examples]] (there are hundreds). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled [[http://www.catb.org/~esr/faqs/smart-questions.html How to ask questions the smart way]]. [[http://www.mikeash.com/getting_answers.html Getting Answers]] is a good starting point too.<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Avoid HTML emails.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
bacause the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Accessing VTK CVS from behind a firewall ===<br />
<br />
Use the sourceforge project:<br />
<br />
http://cvsgrab.sourceforge.net/<br />
<br />
Just download the script and type something like:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xx<br />
<br />
(Thanks to Ingo H. de Boer)<br />
<br />
Also cvsgrab support the following option to access a particular branch:<br />
<br />
-tag <version tag> [optional] The version tag of the files to download<br />
<br />
For example to get the latest 4.4 branch:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xxx<br />
-tag release-4-4<br />
<br />
=== Where can I obtain test and sample datasets? ===<br />
<br />
See [[VTK Datasets|this page]] for details on downloading datasets that VTK can read.<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# 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.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
* [http://public.kitware.com/pipermail/vtkusers/2003-October/070054.html vtk, Python and SWIG - 'state of the union']<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# 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''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
==== GDCM ====<br />
<br />
For a more elaborate DICOM library that supports more image format, you might try [http://gdcm.sourceforge.net GDCM].<br />
Specifically: [http://gdcm.sourceforge.net/html/classvtkGDCMImageReader.html vtkGDCMImageReader] & [http://gdcm.sourceforge.net/html/classvtkGDCMImageWriter.html vtkGDCMImageWriter]<br />
<br />
Grassroots DiCoM is a C++ library for DICOM medical files. It is automatically wrapped to python/C#/Java (using swig). It supports RAW,JPEG (lossy/lossless),J2K,JPEG-LS,RLE and deflated. It also comes with DICOM Part 3,6 & 7 of the standard as XML files.<br />
<br />
If GDCM is too complex to integrate in your environment you can also consider simply using the command line converter: [http://apps.sourceforge.net/mediawiki/gdcm/index.php?title=Gdcmconv gdcmconv] to convert an unsupported DICOM file into something that vtkDICOMImageReader, can support. Typically you would want:<br />
<br />
gdcmconv --raw compressed_input.dcom uncompressed_output.dcom<br />
<br />
==== dicom2 ====<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== vtkVolume16Reader ====<br />
<br />
When searching the vtkusers mailing list a lot of posts are still using vtkVolume16Reader to read in DICOM file. It will works in the following case:<br />
* You know the dimension (cols & rows) of your image<br />
* You know the spacing of your image<br />
* You know the pixel type (pixel type & #components) of your image<br />
* You know Pixel Data (7fe0,0010) is the last element in the image<br />
* You know Pixel Data (7fe0,0010) was sent in uncompressed format (not encapsulated)<br />
<br />
All those requirements are a stronger set of requirements than vtkDICOMImageReader, therefore it is encourage to use vtkDICOMImageReader instead.<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
GDCM 1.x:<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
GDCM 2.x:<br />
IPPSorter ipp;<br />
ipp.Sort( filenames );<br />
zspacing = ipp.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
==== Using ReleaseDataFlag ====<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
==== Use ImmediateModeRendering ====<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
==== Use triangle strips via vtkStripper. ====<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
==== Use a different filter or mapper ====<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use the STL.<br />
However, see the [[VTK Coding Standards]] for limitations.<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
==== Vim indentation ====<br />
<br />
[[user talk:Andy|Andy Cedilnik]] has some information on following the VTK coding guidelines using vim. You may place the following in your <code>~/.vimrc</code> file<br />
set tabstop=2 " Tabs are two characters<br />
set shiftwidth=2 " Indents are two charactes too<br />
set expandtab " Do not use tabs<br />
set cinoptions={1s,:0,l1,g0,c0,(0,(s,m1<br />
"Keep tabs in makefiles as they are significant:<br />
:autocmd BufRead,BufNewFile [Mm]akefile :set noexpandtab<br />
<br />
=== How to display transparent objects? ===<br />
(keywords: alpha, correct, depth, geometry, object, opacity, opaque, order, ordering, peel, peeling, sorting, translucent, transparent.)<br />
<br />
When opaque geometry is rendered, there is no need to sort it because the depth buffer (or z-buffer) is used and the sorting is done automatically by keeping the geometry closest to the viewpoint at<br />
a given pixel. (It is easy because it is a MAX/MIN calculation, not a real sorting).<br />
<br />
With translucent geometry the final color of a pixel is the contribution of all the geometry primitives visible through the pixel. The color of the pixel is the result of <b>a</b> blending operation between the colors of all visible primitives. Blending operations themselves are usually order-dependent (ie not commutative). That's why depth sorting is required. There are two ways to fix the ordering in VTK:<br />
<br />
*1. Append all your polygonal geometry with [http://www.vtk.org/doc/nightly/html/classvtkAppendPolyData.html vtkAppendPolyData] and pass it to [http://www.vtk.org/doc/nightly/html/classvtkDepthSortPolyData.html vtkDepthSortPolyData]. See this tcl [http://public.kitware.com/cgi-bin/viewcvs.cgi/*checkout*/Hybrid/Testing/Tcl/depthSort.tcl?root=VTK&content-type=text/plain example]. Depth sorting is done per centroid of geometry primitives, not per pixel. For this reason it is not exact but it solves <b>most</b> of the ordering and gives result usually good enough.<br />
* 2. If the graphics card supports it, use "[[VTK/Depth_Peeling | depth peeling]]". It performs per pixel sorting (better result) but it is really slow.<br />
<br />
=== What's the deal with SetInput() vs. SetInputConnection()? ===<br />
(keywords: SetInput, SetInputConnection, vtkAlgorithm, algorithm, pipeline, source)<br />
<br />
In the transition from VTK 4 to VTK 5, the VTK pipeline executive was completely cleaned up and redesigned. The fundamental idea behind the new pipeline is that the "pipeline" should consist of a chain of "algorithm" objects.<br />
The algorithms are connected together with the familiar b->SetInputConnection(a->GetOutputPort()) methods.<br />
<br />
So how is this different from SetInput()/GetOutput()? The difference between an "OutputPort" and an "Output" is as follows:<br />
<br />
* OutputPort (''vtkAlgorithmOutput''): A trivial object that says "I am output port N of algorithm X" (usually N = 0).<br />
* Output (''subclass of vtkDataObject''): A container for data produced by any VTK code.<br />
<br />
The "OutputPort" method does not presuppose anything about what data (if any) will pass along the pipeline. It could simply signify that algorithm "a" must execute before algorithm "b". This provides enormous flexibility. Trust the VTK designers here, it's better to do things this way than to have the user grab the actual data object from the output of one algorithm and shove it into the input of another.<br />
<br />
However, any newcomer to VTK will quickly notice that the use of SetInputConnection() is not universal. The reason is this: only vtkAlgorithm objects can have a SetInputConnection() or GetOutputPort() method. Some objects that can take inputs are not derived from vtkAlgorithm. For example vtkImageActor is a vtkProp3D and therefore it cannot be a vtkAlgorithm (VTK never uses multiple inheritance). This is a case of an old VTK object that doesn't "fit" the new VTK 5 pipeline. However, the VTK developers did not want to throw away such useful classes when the pipeline was redesigned. Instead, such classes are still served by the backwards-compatible SetInput() method.<br />
<br />
So, use SetInputConnection() whenever you can, but if there is no SetInputConnection(), then go ahead and use SetInput(). There is nothing wrong with doing so. The new pipeline is backwards compatible with the old pipeline methods.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows and Mac workstations.<br />
<br />
=== What Graphics Cards work with VTK ===<br />
<br />
VTK uses OpenGL to perform almost all of its rendering and some graphics cards/drivers have better support for OpenGL than others. This is not a listing of what cards perform well. It is a listing of what cards actually produce correct results. Here is a list of cards and their status roughly in best to worst order.<br />
<br />
* Any Nvidia desktop card on Windows -- 100% compatible<br /> <br />
* Any ATI desktop cards on Windows -- 100% compatible<br /><br />
* Mesa -- most releases pass all VTK tests<br /><br />
* Microsoft Software OpenGL -- passes all VTK tests but does have a couple bugs<br /><br />
* Mac graphics cards -- these usually pass all VTK tests. Older cards may have some issues, for example, the ATI Rage 128 Pro does not support textures larger than 1024x1024.<br /><br />
* Non-linux UNIX cards (Sun HP SGI) -- These generally work<br /><br />
* Any Nvidia card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Any ATI card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Nvidia laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests<br /><br />
* ATI laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests (e.g. [http://public.kitware.com/pipermail/vtkusers/2004-August/075966.html ATI Mobility Radeon 9600])<br /><br />
* Intel Extreme Graphics -- fails some VTK tests<br /><br />
<br />
=== How do I build the examples on the PC running Windows? ===<br />
<br />
Since building the C++ examples on the PC isn't all that easy, here are<br />
some instructions from Jack McInerney.<br />
<br />
Steps for creating a VTK C++ project 8/14/96<br />
<br />
This is based on what I learned creating a project to run the Mace<br />
example. These steps allowed me to successfully built and run this example.<br />
<br />
# Create a console project (File, New, then select Console application).<br />
# Add the files of interest to the project. (e.g., Mace.cxx)<br />
# Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies<br /> 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<br />
# 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).<br />
# 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 <br /> This is a self extracting archive which contains these files. Simply place them in your windows system directory.<br />
# Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless<br /><br />
<br />
When you go to run the program, it will bomb out unless it can find 2<br />
DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the<br />
project directory or the C:\WINDOWS directory. These files are supplied<br />
on the vtk CD-ROM (in the vtk\bin directory).<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
vtk builds on 64 bit systems, that is, systems where sizeof(void*) is 64 bits. However, parts of the vtk codebase are not 64 bit clean and so runtime problems are likely if that code is used.<br />
<br />
===== General =====<br />
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.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5 and later, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work well with 64 bit Cocoa on Mac OS X 10.5 and later.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== What size swap space should I use on a PC? ===<br />
<br />
Building vtk on the PC requires a significant amount of memory (at least<br />
when using Visual C++)... but the final product is nice and compact. To<br />
build vtk on the PC, we recommend setting the min/max swap space to at<br />
least 400MB/500MB (depending on how much RAM you have... the sum of RAM<br />
and swap space should be roughly 500+ MB).<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
See http://paraview.org/Wiki/ParaView_And_Mesa_3D.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
On Mac OS X, there are (at least) two kinds of executables:<br />
* [http://developer.apple.com/documentation/MacOSX/Conceptual/BPInternational/Articles/InternatSupport.html#//apple_ref/doc/uid/20000278-73764 Application Bundles]<br />
* plain UNIX executables<br />
<br />
For a program to be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction) it really should be an Application Bundle. If a plain UNIX executable tries, there will be various bugs, such as keyboard and mouse events not working reliably.<br />
<br />
Many, but not all, of the example VTK applications are built as plain UNIX executables, and thus have these problems. This is [http://www.vtk.org/Bug/bug.php?op=show&bugid=2025 VTK bug 2025].<br />
<br />
When you build your own VTK application, it is best to make it in the form of an Application Bundle. With CMake 2.0.5 or later, simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an Application Bundle (perhaps because your app needs command line parameters) you might be able to avoid the above problems by adding an [http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/ConfigFiles.html#//apple_ref/doc/uid/20002091-SW1 __info_plist section] to your Mach-O executable. If you succeed, please post to the VTK list.<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.4 and older, the short answer is "no".<br />
<br />
For VTK CVS the short answer is "mostly". You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. The usual settings are:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk <br />
<br />
This will result in a Universal build. However, there may be runtime bugs due to VTK's use of TRY_RUN. Work is being done to improve this situation.<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
=== How can a user process access more than 2 GB of ram in 32-bit Windows? ===<br />
<br />
By default on Windows, the most memory that a user process can access is 2 GB, no matter how much RAM you have installed in your system. With Windows XP Professional you can make it possible for a process to use up to 3 GB of memory by doing two things:<br />
<br />
1) Modify the boot parameters in boot.ini (on my 32 bit WinXP Pro machine, it's in: "C:\boot.ini") to tell the operating system that you want user processes to have access to up to 3GB of RAM (This is a really important file, and if you don't know what you are doing, stop reading this and go back to work!). This is done by adding the /3GB flag to the line of the file that tells the boot loader where the operating system is. My boot.ini file looks like:<br />
<br />
[boot loader]<br />
timeout=30<br />
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS<br />
[operating systems]<br />
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /3GB<br />
<br />
This is a very bad file to make mistakes on, so don't - it may be very difficult to repair your computer to boot if you mess up this file. There is a nice description of this in the Microsoft article <br />
[http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx Memory Support and Windows Operating Systems].<br />
<br />
2) The other thing that you need to do is make your executable LARGEADDRESSAWARE. Assuming that you have a Windows binary that you want to try this on, you can use the 'editbin' utility that comes with Visual Studio to change the setting of one bit (the IMAGE_FILE_LARGE_ADDRESS_AWARE bit) in the image header of the executable. For a program 'prog.exe' you can make the change by<br />
<br />
editbin /LARGEADDRESSAWARE prog.exe<br />
<br />
Of course, depending on how your program handles memory you might find that it crashes when you try to use the extra memory, but that's a separate issue. If you are compiling your program with a version of Visual Studio you should be able to find the switch to make your program /LARGEADDRESSAWARE.<br />
<br />
=== Shared builds of VTK and debugging QVTKWidget using Visual Studio ===<br />
<br />
Assuming that you have built a shared build of VTK and you may or may<br />
not have a set it up such that there is a path to the release version<br />
of VTK in your PATH statement.<br />
<br />
Then if you debug a project that is using QVTKWidget, you will come<br />
across a problem in that if you are debugging a debug version; the<br />
application depends upon the debug version of QVTK.dll which will<br />
depend upon QtGui4d.dll (among others) and load it. But, because the<br />
release version of QVTK.dll is in the path, QtGiu4.dll will also be<br />
loaded preventing the application from running. You will get a<br />
"QWidget: Must construct a QApplication before a QPaintDevice"<br />
message.<br />
<br />
The solution to this problem is to set the path to the correct build<br />
of VTK on the "'''Debugging'''" properties of your project. Right click on<br />
your project, bring up the properties dialog, and select "'''Debugging'''"<br />
from the list on the left. There should be an "'''Environment'''" line. You<br />
can add variables here using key=value pairs.<br />
For example, add the following line:<br />
PATH=<Path To VTK>\bin\$(OutDir);%PATH%<br />
You can then add the same line to other configurations, such as the release one, by selecting<br />
them from the top left drop down box labelled '''Configuration'''.<br />
<br />
$(OutDir) will be set by Visual Studio to either Debug or Release,<br />
depending upon what configuration you have selected. Make sure <br />
that ;%PATH% is appended so that Qt and other files can be appended <br />
to the PATH statement.<br />
<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes in VTK between 3.2 and 4.0 ===<br />
<br />
* 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.<br />
<br />
* 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<br />
<br />
* Added special methods to data arrays to replace methods like<br />
<br />
tc SetTCoord i x y 0<br />
<br />
or<br />
<br />
vc SetVector i vx vy vz<br />
<br />
in interpreted languages (Tcl, Python, Java). Use:<br />
<br />
tc SetTuple2 i x y<br />
<br />
or<br />
<br />
vc SetTuple3 i vx vy vz<br />
<br />
* 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.<br />
<br />
* vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.<br />
<br />
* 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.<br />
<br />
* 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).<br />
<br />
* The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.<br />
<br />
* Support for reading and writing PGM and JPEG images has been included.<br />
<br />
* 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.<br />
<br />
* 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 Imaging 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.<br />
<br />
* 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.<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* 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.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* 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.<br />
<br />
* 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:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== How do I upgrade my existing C++ code from 3.2 to 4.x? ===<br />
<br />
This is (a corrected version of) an email that was posted to vtkusers.<br />
Please feel free to correct or add anything.<br />
<br />
{| cellspacing="3" <br />
|- valign="top"<br />
|width="55%" bgcolor="#f0f0ff" style="border:1px solid #ffc9c9;padding:1em;padding-top:0.5em;"|<br />
<br />
I've just ported my medium-sized (40K lines) application from vtk3.2 to<br />
vtk4.x. I thought I would share my experiences with you, in case there<br />
were people out there contemplating it but a bit scared.<br />
<br />
One source of information for upgrading code is:<br />
<br />
http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the<br />
script in the zip file.<br />
<br />
So,<br />
<br />
I switched all my include directories to the new VTK ones and<br />
recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and<br />
vtkTCoords which have both been removed. Where I was using single value<br />
scalars, like this:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetNumberOfScalars(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetScalar(i,2.3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *scalars = vtkFloatArray::New();<br />
scalars->SetNumberOfComponents(1);<br />
scalars->SetNumberOfTuples(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetTuple1(i,2.3);<br />
...<br />
<br />
OK so far, far fewer errors.<br />
<br />
Where I had 2D texture coordinates:<br />
<br />
vtkTCoords *tcoords = vtkTCoords::New();<br />
tcoords->SetNumberOfTCoords(N);<br />
...<br />
float p[3];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTCoord(i,p);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *tcoords = vtkFloatArray::New();<br />
tcoords->SetNumberOfComponents(2);<br />
tcoords->SetNumberOfTuples(N);<br />
...<br />
float p[2];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTuple(i,p);<br />
....<br />
<br />
All well and good, still fewer errors. Make sure you call<br />
SetNumberOfComponents *before* SetNumberOfTuples else you'll get<br />
problems (I did!).<br />
<br />
Where I was creating 0-255 image data and had been using:<br />
<br />
vtkScalars* scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
...<br />
<br />
Going well!<br />
<br />
When creating RGB images, I had been using:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfScalars(X*Y);<br />
...<br />
scalars->SetActiveComponent(0);<br />
scalars->SetScalar(i,val1);<br />
scalars->SetActiveComponent(1);<br />
scalars->SetScalar(i,val2);<br />
scalars->SetActiveComponent(2);<br />
scalars->SetScalar(i,val3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfTuples(X*Y);<br />
...<br />
scalars->SetComponent(i,0,val1);<br />
scalars->SetComponent(i,1,val2);<br />
scalars->SetComponent(i,2,val3);<br />
...<br />
<br />
My remaining errors concerned vtkWin32OffscreenRenderWindow that has<br />
been removed. Where I had been using:<br />
<br />
vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New();<br />
offscreen->SetOffScreenRendering(1);<br />
...<br />
<br />
All done. I'd had to throw in some #include "vtkFloatArray.h" and things<br />
like that of course. Zero compile errors.<br />
<br />
Had to remember to link against the new vtk lib files, so I removed<br />
<br />
vtkdll.lib <br />
<br />
and added<br />
<br />
vtkCommon.lib<br />
vtkGraphics.lib<br />
<br />
etc.<br />
<br />
Zero link errors. My program is up and running again, no apparant<br />
problems. Plus now I can use all the new features of vtk4. (And I'm sure<br />
it's faster but maybe that's my imagination.)<br />
<br />
All this took me about three hours.<br />
<br />
Bye!<br />
<br />
Tim.<br />
|}<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was releaseed in February 2003. VTK 4.4 (which was an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, 5.0.3 in March 2007, and 5.0.4 in January 2008.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# 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.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* 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.<br />
#* 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.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* 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.<br />
* 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).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* 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. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* 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.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
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.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== Using Volume Rendering in VTK ===<br />
<br />
I recently updated my VTK CVS version. And my c++ code that use to work fine are now complaining about:<br />
<br />
undefined reference to `vtkUnstructuredGridAlgorithm::SetInput(vtkDataObject*)'<br />
undefined reference to `vtkUnstructuredGridAlgorithm::GetOutput()' <br />
<br />
There is now a new subfolder and a new option to enable building the VolumeRendering library. You have to turn VTK_USE_VOLUMERENDERING to ON in order to use it. Also make sure that your executable is linking properly to this new library:<br />
<br />
ADD_EXECUTABLE(foo foo.cxx)<br />
TARGET_LINK_LIBRARIES(foo vtkVolumeRendering)<br />
<br />
=== API Changes in VTK 5.2 ===<br />
<br />
==== <tt>vtkProp::RenderTranslucentGeometry()</tt> is gone ====<br />
<br />
<tt>vtkProp::RenderTranslucentGeometry()</tt> is gone and has been broken down into 3 methods:<br />
* <tt>HasTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderVolumetricGeometry()</tt><br />
<br />
Here is what to change in a vtkProp subclass:<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry only, override <tt>HasTranslucentPolygonalGeometry()</tt> and <tt>RenderTranslucentPolygonalGeometry()</tt>. <b>Just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderTranslucentPolygonalGeometry()</tt> is not enough!</b><br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent volumetric geometry only, override <tt>RenderVolumetricGeometry()</tt>. In this case, just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderVolumetricGeometry()</tt> is OK.<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry and translucent volumetric geometry, override all 3 methods.<br />
<br />
The reason of this change is that <tt>HasTranslucentPolygonalGeometry()</tt> is used to decide if an expensive initialization of the new rendering algorithm of translucent polygonal geometry (depth peeling) is necessary. <tt>RenderTranslucentPolygonalGeometry()</tt> is called multiple times during the rendering of the translucent polygonal geometry of the scene. <tt>RenderVolumetricGeometry()</tt> is called in an additional pass, after depth peeling. For this reason, <b><tt>RenderTranslucentGeometry()</tt> cannot just be marked as deprecated but had to be removed from the API</b>.<br />
<br />
<br />
<br />
==== <tt>vtkImagePlaneWidget</tt> has action names changed ====<br />
from:<br />
enum<br />
{<br />
CURSOR_ACTION = 0,<br />
SLICE_MOTION_ACTION = 1,<br />
WINDOW_LEVEL_ACTION = 2<br />
};<br />
to:<br />
enum<br />
{<br />
VTK_CURSOR_ACTION = 0,<br />
VTK_SLICE_MOTION_ACTION = 1,<br />
VTK_WINDOW_LEVEL_ACTION = 2<br />
};<br />
<br />
==== <tt>GetOutput()</tt> now returns <tt>vtkDataObject</tt> for some algorithms ====<br />
<br />
The following algorithms now work on <tt>vtkGraph</tt> as well as <tt>vtkDataSet</tt>, so no <tt>GetOutput()</tt> longer returns <tt>vtkDataSet</tt>. To obtain the dataset, use <tt>vtkDataSet::SafeDownCast(filter->GetOutput())</tt><br />
* <tt>vtkArrayCalculator</tt><br />
* <tt>vtkAssignAttribute</tt><br />
* <tt>vtkProgrammableFilter</tt><br />
<br />
=== API Changes in VTK 5.4 ===<br />
* empty right now.<br />
=== API Changes in VTK 5.5 ===<br />
<br />
* vtkStreamTracer<br />
Changed<br />
enum Units <br />
{ <br />
TIME_UNIT, <br />
LENGTH_UNIT, <br />
CELL_LENGTH_UNIT <br />
}<br />
to<br />
enum Units<br />
{ <br />
LENGTH_UNIT = 1, <br />
CELL_LENGTH_UNIT = 2 <br />
}<br />
<br />
<br />
Changed<br />
* OUT_OF_TIME = 4<br />
to<br />
* OUT_OF_LENGTH = 4<br />
in enum ''ReasonForTermination''<br />
<br />
<br />
Changed<br />
* LastUsedTimeStep<br />
to<br />
* LastUsedStepSize<br />
<br />
<br />
Changed<br />
* MaximumPropagation<br />
* MaximumIntegrationStep<br />
* MinimumIntegrationStep<br />
* InitialIntegrationStep <br />
from type ''IntervalInformation'' to type ''double''.<br />
<br />
<br />
Added a member variable to the class<br />
* int IntegrationStepUnit<br />
<br />
<br />
The following APIs were '''removed''' from the class:<br />
* void SetMaximumProgration(int unit, double max)<br />
* void SetMaximumProgrationUnit(int unit)<br />
* int GetMaximumPropagationUnit()<br />
* void SetMaximumPropagationUnitToTimeUnit()<br />
* void SetMaximumPropagationUnitToLengthUnit()<br />
* void SetMaximumPropagationUnitToCellLengthUnit()<br />
* void SetMinimumIntegrationStep(int unit, double step)<br />
* void SetMinimumIntegrationStepUnit(int unit)<br />
* int GetMinimumIntegrationStepUnit()<br />
* void SetMinimumIntegrationStepUnitToTimeUnit()<br />
* void SetMinimumIntegrationStepUnitToLengthUnit()<br />
* void SetMinimumIntegrationStepUnitToCellLengthUnit()<br />
* void SetMaximumIntegrationStep(int unit, double step)<br />
* void SetMaximumIntegrationStepUnit(int unit)<br />
* int GetMaximumIntegrationStepUnit()<br />
* void SetMaximumIntegrationStepUnitToTimeUnit()<br />
* void SetMaximumIntegrationStepUnitToLengthUnit()<br />
* void SetMaximumIntegrationStepUnitToCellLengthUnit()<br />
* void SetInitialIntegrationStep(int unit, double step)<br />
* void SetInitialIntegrationStepUnit(int unit)<br />
* int GetInitialIntegrationStepUnit()<br />
* void SetInitialIntegrationStepUnitToTimeUnit()<br />
* void SetInitialIntegrationStepUnitToLengthUnit()<br />
* void SetInitialIntegrationStepUnitToCellLengthUnit()<br />
* void SetIntervalInformation(int unit, double interval, IntervalInformation& currentValues)<br />
* void SetIntervalInformation(int unit,IntervalInformation& currentValues)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength, double speed)<br />
* static double ConvertToTime(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToCellLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToUnit(IntervalInformation& interval, int unit, double cellLength, double speed)<br />
<br />
<br />
The following APIs were added to the class:<br />
* int GetIntegrationStepUnit()<br />
* void SetIntegrationStepUnit(int unit)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength)<br />
* static double ConvertToLength(double interval, int unit, double cellLength)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength)<br />
<br />
<br />
* vtkInterpolatedVelocityField<br />
Added a new member variable and two associated functions:<br />
* bool NormalizeVector<br />
* vtkSetMacro(NormalizeVector, bool)<br />
* vtkGetMacro(NormalizeVector, bool)<br />
<br />
== OpenGL requirements ==<br />
<br />
=== Terminology ===<br />
<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
<br />
==== Linux/Unix ====<br />
<br />
Two ways:<br />
<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
<br />
* vendor specific tool<br />
<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
=== VTK 5.2 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.2? ====<br />
<br />
Same answer than for VTK 5.0.<br />
<br />
==== What is the minimal OpenGL version required by VTK5.2 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>, <tt>vtkHAVSVolumeMapper</tt>,<br />
<tt>vtkGLSLShaderProgram</tt>, depth peeling and some hardware offscreen rendering using framebuffer objects (FBO).<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
If you want to use <tt>vtkHAVSVolumeMapper</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_draw_buffers</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_program</tt><br />
* <tt>GL_ARB_vertex_program</tt><br />
* <tt>GL_EXT_framebuffer_object</tt><br />
* either <tt>GL_ARB_texture_float</tt> or <tt>GL_ATI_texture_float</tt><br />
<br />
The following extension or OpenGL version is used by <tt>vtkHAVSVolumeMapper</tt> if provided (at runtime), but it is optional:<br />
* <tt>GL_ARB_vertex_buffer_object</tt> or OpenGL>=1.5<br />
<br />
If you want to use <tt>vtkGLSLShaderProgram</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_shading_language_100</tt> or OpenGL>=2.0,<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0.<br />
<br />
Depth peeling ( see [[VTK/Depth_Peeling | VTK Depth Peeling]] for more information) requires (at runtime):<br />
* <tt>GL_ARB_depth_texture</tt> or OpenGL>=1.4<br />
* <tt>GL_ARB_shadow</tt> or OpenGL>=1.4<br />
* <tt>GL_EXT_shadow_funcs</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_occlusion_query</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
* <tt>GL_SGIS_texture_edge_clamp</tt> or <tt>GL_EXT_texture_edge_clamp</tt> or OpenGL>=1.2<br />
<br />
Hardware-based offscreen rendering using framebuffer object (FBO) will be used as the default offscreen method if the following extensions or OpenGL version are available (at runtime):<br />
* <tt>GL_EXT_framebuffer_object</tt><br />
and either <br />
* <tt>GL_ARB_texture_non_power_of_two</tt> or OpenGL>=2.0<br />
or<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
In addition, if the the framebuffer needs a stencil buffer, extension <tt>GL_EXT_packed_depth_stencil</tt> is required. Even if all those extensions are supported, the chosen FBO format might<br />
not be supported by the card; in this case, this method of offscreen rendering is not used.<br />
<br />
== Miscellaneous questions ==<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
== Legal issues ==<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Development]]<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. We think it's pretty reasonable. We do restrict the<br />
distribution of modified code. This is primarily a revision control<br />
issue. We don't want a bunch of renegade vtks running around without us<br />
having some idea why the changes were made and giving us a chance to<br />
incorporate them into the general release.<br />
<br />
The text of the VTK copyright is available [http://www.vtk.org/copyright.php here].<br />
<br />
=== What is the deal with the patents ===<br />
<br />
As the copyright mentions there are some patents used in VTK. If you use<br />
any code in the Patented/ directory for commercial application you<br />
should contact the patent holder and obtain a license.<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by General Electric Company: vtkDecimate, vtkMarchingCubes,<br />
vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface.<br />
The GE contact is:<br />
<br />
Carl B. Horton<br />
Sr. Counsel, Intellectual Property<br />
3000 N. Grandview Blvd., W-710<br />
Waukesha, WI 53188<br />
Phone: (262) 513-4022<br />
E-Mail: mailto:Carl.Horton@med.ge.com<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by Kitware, Inc.: vtkGridSynchronizedTemplates3D,<br />
vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and<br />
vtkSynchronizedTemplates3D. The Kitware contact is:<br />
<br />
Ken Martin<br />
Kitware<br />
28 Corporate Drive, Suite 204,<br />
Clifton Park, NY 12065<br />
Phone:1-518-371-3971<br />
E-Mail: mailto:kitware@kitware.com<br />
<br />
=== Can VTK be used as part of a project distributed under a GPL License ? ===<br />
<br />
==== Short Answer ====<br />
<br />
Yes, it is fine to take VTK code and to include it in a project that is distributed under a GPL license.<br />
<br />
==== Long Answer ====<br />
<br />
===== Terms =====<br />
<br />
Let's call project X the larger project that:<br />
<br />
# Will include source code from VTK (in part or as a whole)<br />
# Will be distributed under GPL license<br />
<br />
Note in particular that:<br />
<br />
# The copyright notices in VTK files must be kept.<br />
# If VTK files are modified by the developers of project X, that fact must be clearly indicated.<br />
# Only the modifications of VTK files made by the developers of project X will be covered by a GPL license. The original VTK code remains covered by the VTK license.<br />
# The collection of copyrighted works (project X in this case), that includes VTK (in part or as a whole) and their software will be covered by a GPL license.<br />
<br />
===== Details =====<br />
<br />
As the [http://www.vtk.org/copyright.php VTK license] is a variation of the [http://www.opensource.org/licenses/bsd-license.php Modified BSD license], to which only the following term has been added:<br />
<br />
Modified source versions must be plainly marked as such, <br />
and must not be misrepresented as being the original software.<br />
<br />
and that the Modified BSD license is itself compatible with the GPL <br />
<br />
http://www.gnu.org/philosophy/license-list.html (Modified BSD license)<br />
<br />
Then the VTK license is also compatible with the GPL license. Since the terms of the GPL license do not preclude the additional term of the VTK license from being followed.<br />
<br />
NOTE: The licenses are only '''one way compatible'''.<br />
<br />
* You can use VTK code inside a GPL licensed project.<br />
* You '''can not''' use GPL licensed code inside VTK.<br />
<br />
That is the reason why there are no GPL third party libraries in VTK. Having GPL third party libraries in VTK would prevent closed source projects from being built against VTK.<br />
<br />
== Common problems and their solutions ==<br />
* There are some problems may that arise while building VTK that have very straight forward solutions. [[VTK/BuildingProblems|Here]] they are.<br />
* There are some problems that arise frequently that have very straight forward solutions. [[VTK/CommonProblems|Here]] they are.<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/VTK_6_Migration/vtkType_deprecations&diff=52189VTK/VTK 6 Migration/vtkType deprecations2013-04-08T17:05:11Z<p>Seanmcbride: </p>
<hr />
<div>vtkType.h's VTK_LARGE_ID has been deprecated and renamed to VTK_ID_MAX. A VTK_ID_MIN was also added, which did not exist before.<br />
<br />
To update your code, simply find-replace all VTK_LARGE_ID to VTK_ID_MAX.</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/VTK_6_Migration/OS_Compiler_Support&diff=52188VTK/VTK 6 Migration/OS Compiler Support2013-04-08T17:04:20Z<p>Seanmcbride: Created page with "The following compilers are no longer supported: Visual Studio 7.0 and older, Borland 5.6 and older, gcc 2.x. The following operating systems are no longer supported: Windows 9x..."</p>
<hr />
<div>The following compilers are no longer supported: Visual Studio 7.0 and older, Borland 5.6 and older, gcc 2.x.<br />
<br />
The following operating systems are no longer supported: Windows 9x, Mac OS X 10.4 and older.</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/VTK_6_Migration_Guide&diff=52187VTK/VTK 6 Migration Guide2013-04-08T17:03:03Z<p>Seanmcbride: </p>
<hr />
<div>[[VTK/VTK_6_Migration/Overview | Overview]]<br />
<br />
[[VTK/VTK_6_Migration/Replacement_of_SetInput | Replacement of SetInput() with SetInputData() and SetInputConnection()]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_GetProducerPort | Removal of GetProducerPort() from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_ GetPipelineInformation | Removal of GetPipelineInformation and GetExecutive from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_Update | Removal of Pipeline Update Methods from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_Execute | Removal of ExecuteInformation() and ExecuteData() from Algorithm Superclasses]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_SetExtentTranslator | Removal of SetExtentTranslator and GetExtentTranslator from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_CopyInformation | Removal of CopyInformation and CopyTypeSpecificInformation from vtkDataObject and vtkImageData]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_CopyInformationToPipeline | Removal of CopyInformationToPipeline and CopyInformationFromPipeline from vtkDataObject and sub-classes]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_GetEstimatedMemorySize | Removal of GetEstimatedMemorySize() method from vtkDataObject and vtkImageData ]]<br />
<br />
[[VTK/VTK_6_Migration/Removal of SetWholeExtent | Removal of SetWholeExtent() from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal of ShouldIReleaseData | Removal of ShouldIReleaseData() and ReleaseDataFlag methods from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal of Methods for Manipulating Update Extent | Removal of vtkDataObject Methods for Manipulating Update Extent]]<br />
<br />
[[VTK/VTK_6_Migration/Change to Crop | Change to Crop() in vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Changes to Scalars Manipulation Functions | Changes to Scalars Manipulation Functions in vtkImageData]]<br />
<br />
[[VTK/VTK_6_Migration/Change to CopyOriginAndSpacingFromPipeline | Change to CopyOriginAndSpacingFromPipeline in vtkImageData]]<br />
<br />
[[VTK/VTK_6_Migration/Changes to SetAxisUpdateExtent | Changes to SetAxisUpdateExtent and GetAxisUpdateExtent in vtkImageData]]<br />
<br />
[[VTK/VTK_6_Migration/Change to AllocateOutputData | Change to AllocateOutputData() in vtkImageAlgorithm]]<br />
<br />
[[VTK/VTK_6_Migration/Changes to vtkProcrustesAlignmentFilter | Changes to vtkProcrustesAlignmentFilter]]<br />
<br />
[[VTK/VTK_6_Migration/Removal of vtkPlot3DReader | Removal of vtkPlot3DReader]]<br />
<br />
[[VTK/VTK_6_Migration/vtkType deprecations | vtkType deprecations]]<br />
<br />
[[VTK/VTK_6_Migration/OS_Compiler_Support | Dropped support for old OSes and compilers]]</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/VTK_6_Migration/Overview&diff=52186VTK/VTK 6 Migration/Overview2013-04-08T17:00:24Z<p>Seanmcbride: moving note elsewhere</p>
<hr />
<div>= Summary =<br />
<br />
One of the main goals of the pipeline re-architecture between VTK 4 and 5 was to 1) move the execution logic from data and process (algorithm) objects to a new set of classes called executives. This was to enable easy modification and extension of the pipeline (execution) code as well as to 2) separate data and execution “models” in order to simplify the code for both. The changes between VTK 4 and 5 achieved the first goal fairly well but did not tackle the second goal in order to preserve backwards compatibility with VTK 4. The work described herein has two major goals:<br />
<br />
# To remove the VTK 4 backwards compatibility layer introduced in VTK 5 in order to simplify the toolkit.<br />
# To carry the work started in VTK 5 to its logical conclusion by completely separating data and executions models<br />
<br />
This work comes at a cost: many of the changes described here are not backwards compatible with VTK 4 and some of them are not backwards compatible with VTK 5. In this document, we summarize the changes introduced as part of this work as well as provide guidance in migrating existing code forward. <br />
<br />
= Overview of Changes =<br />
<br />
The changes introduced as part of this work can be classified under a few major categories:<br />
<br />
# Removal of VTK 4 backwards compatibility superclasses: This includes vtkProcessObject, vtkSource and all of their subclasses. These classes were changed in VTK 5 in order to provide backwards compatibility. In VTK 6, all pipeline modules should subclass from vtkAlgorithm or one of its subclasses.<br />
# Removal of the pipeline meta-data API from vtkDataObject: As of VTK 5, the main containers of all pipeline meta-data and heavy-data are vtkInformation objects that represent input and output information for algorithms. Data objects should no longer be used to store meta-data (e.g. Whole Extent, Update Extent etc.). The vtkDataObject API for pipeline meta-data was kept for backwards compatibility to VTK 4 and was removed as part of this work.<br />
# Removal of data objects’ dependency on the pipeline code (algorithms and executives): The aims of this change are to simplify data object classes and to allow for the separation of data and execution model libraries as part of the ongoing modularization effort. This change causes a few incompatibilities explained in detail below.<br />
<br />
= Changes in Detail =<br />
<br />
== Removal of VTK 4 Backwards Compatibility Superclasses ==<br />
<br />
The changes to the pipeline and pipeline modules introduced in VTK are explained in detail in a PDF document in VTK’s source code distribution: VTK/Utilities/Upgrading/TheNewVTKPipeline.pdf. If you are not familiar with these changes and find that your code stopped compiling due to changes described in this section, we recommend that you review that document first. It described in more detail the changes to pipeline modules and how to migrate to VTK 5.<br />
<br />
In order to the transition to the VTK 5 pipeline implementation as smoothly as possible, VTK 5 introduced a set of backwards compatibility classes. These included modified versions of previous algorithm superclasses including vtkProcessObject, vtkSource, vtkXXXSource (where XXX represents various data types) and vtkXXXToYYYFilter (where XXX and YYY are various data types). VTK 6 removes all of these classes and requires that all pipeline modules subclass from vtkAlgorithm or one of its subclasses and use the RequestInformation / RequestUpdateExtent / RequestData API rather than ExecutionInformation / PropagateUpdateExtent / Execute API. Below is a full list of backwards compatibility classes that were removed in VTK 6. If your code fails to compile because it refers to any of these classes, it is time to migrate to the VTK 5 API.<br />
<br />
* Filtering/vtkDataObjectSource<br />
* Filtering/vtkDataSetSource<br />
* Filtering/vtkDataSetToDataSetFilter<br />
* Filtering/vtkDataSetToImageFilter<br />
* Filtering/vtkDataSetToPolyDataFilter<br />
* Filtering/vtkDataSetToStructuredGridFilter<br />
* Filtering/vtkDataSetToStructuredPointsFilter<br />
* Filtering/vtkDataSetToUnstructuredGridFilter<br />
* Filtering/vtkImageInPlaceFilter<br />
* Filtering/vtkImageMultipleInputFilter<br />
* Filtering/vtkImageMultipleInputOutputFilter<br />
* Filtering/vtkImageSource<br />
* Filtering/vtkImageToImageFilter<br />
* Filtering/vtkImageTwoInputFilter<br />
* Filtering/vtkPointSetSource<br />
* Filtering/vtkPointSetToPointSetFilter<br />
* Filtering/vtkPolyDataSource<br />
* Filtering/vtkPolyDataToPolyDataFilter<br />
* Filtering/vtkProcessObject<br />
* Filtering/vtkRectilinearGridSource<br />
* Filtering/vtkRectilinearGridToPolyDataFilter<br />
* Filtering/vtkSource<br />
* Filtering/vtkStructuredGridSource<br />
* Filtering/vtkStructuredGridToPolyDataFilter<br />
* Filtering/vtkStructuredGridToStructuredGridFilter<br />
* Filtering/vtkStructuredPointsSource<br />
* Filtering/vtkStructuredPointsToPolyDataFilter<br />
* Filtering/vtkStructuredPointsToStructuredPointsFilter<br />
* Filtering/vtkStructuredPointsToUnstructuredGridFilter<br />
* Filtering/vtkUnstructuredGridSource<br />
* Filtering/vtkUnstructuredGridToPolyDataFilter<br />
* Filtering/vtkUnstructuredGridToUnstructuredGridFilter<br />
* FilteringvtkStructuredPointsToUnstructuredGridFilter<br />
* FilteringvtkUnstructuredGridToUnstructuredGridFilter<br />
* Imaging/vtkImageSpatialFilter<br />
<br />
== Removal of All Pipeline Meta-Data API from vtkDataObject== <br />
<br />
Examples of pipeline meta-data include WholeExtent, UpdateExtent, MaximumNumberOfPieces, UpdateNumberOfPieces, UpdatePiece, UpdateGhostLevel, ScalarType and NumberOfScalarComponents. In VTK 5, this meta-data is represented by vtkInformation keys such as vtkStreamingDemandDriven::WHOLE_EXTENT() and vtkStreamingDemandDrivenPipeline::UPDATE_EXTENT() and flow up and down the pipeline through input and output information objects passed to ProcessRequest (hence to RequestInformation, RequestUpdateExtent and RequestData). In VTK 4, this was achieved using vtkDataObjects and the vtkDataObject API (methods such as Set/GetWholeExtent, Set/GetUpdateExtent etc.). VTK 5 maintained this API as well as the associated vtkDataObject data members. The Executives had the responsibility of synching vtkDataObject data members with data in input and output information objects. The code to achieve this was hard to maintain and fragile. Furthermore, developers were often confused by the API to obtain pipeline specific meta-data (such as WholeExtent – the extent of the entire image available from a source or a reader) and data specific meta-data (such as Extent – the extent of the image data currently in memory). For example, we encountered the following in several places in VTK code as well as in other applications that used VTK:<br />
<br />
<source lang="cpp"><br />
vtkImageData* image = vtkImageData::New();<br />
int extent[6] = {0, 10, 0, 10, 0, 10};<br />
image->SetExtent(extent);<br />
image->SetUpdateExtent(extent);<br />
image->SetWholeExtent(extent);<br />
image->AllocateScalars();<br />
</source><br />
<br />
The correct implementation (which only uses SetExtent) was not clear to many developers and they chose the “safe” route of setting everything related to Extent to the same value – which is not really safe since it is a bug.<br />
<br />
VTK 6 removes all pipeline meta-data API from data object and requires the use of the appropriate information keys to create, modify and read pipeline meta-data. Refer to the Appendix for a full list of methods removed from vtkDataObject.<br />
<br />
== Removal of Data Objects’ Dependency on the Pipeline ==<br />
<br />
The final set of changes introduced as part of this work remove the dependency of vtkDataObject and its subclasses on the pipeline objects (executives and algorithms) completely decoupling the VTK “data model” from the VTK “execution model”. This has two major advantages:<br />
<br />
* Support for modularization: With these changes, it will be possible to create a small, self-contained library that only includes support for core classes and data model classes. This will enable developers to leverage VTK’s data model in their applications without significant code bloat.<br />
* Simplification of data object and pipeline execution APIs: These changes eliminate a significant amount of API duplication between algorithms and executives simplifying the VTK API. For example, to update (i.e. to force the execution of an) algorithm, the developer now has to access one method: vtkAlgorithm:Update() rather than several distributed among data objects and algorithms.<br />
<br />
Some of the changes introduced to remove this dependency are transparent to all but advanced users/developers of VTK. Others impact many developers that use VTK. The first of these is that all pipeline execution API was removed from vtkDataObject. Therefore, code similar to the following will not compile:<br />
<br />
<source lang="cpp"><br />
vtkDataObject* dobj = someAlgorithm->GetOutput();<br />
dobj->Update();<br />
</source><br />
<br />
This needs to be replaced with the following<br />
<br />
<source lang="cpp"><br />
someAlgorithm->Update();<br />
</source><br />
<br />
The second backwards-incompatible change is probably the one that will impact the most code. In VTK 4, pipeline objects were connected as follows:<br />
<br />
<source lang="cpp"><br />
someFilter->SetInput(someReader->GetOutput());<br />
</source><br />
<br />
In VTK 5, this was changed to:<br />
<br />
<source lang="cpp"><br />
someFilter->SetInputConnection(someReader->GetOutputPort());<br />
</source><br />
<br />
However, the SetInput() and related methods were preserved for backwards compatibility. This method and all related functions, such as SetSource, were removed in VTK 6. The main reason behind this is that it is impossible to preserve this method while decoupling data objects from pipeline objects. In VTK 5, SetInput() was implemented under the hood using SetInputConnection() but this required access to the algorithm and its output port given a data object. In VTK 6, since the data object no longer has a reference to the algorithm that produced it, it is not possible to establish a pipeline connection given only a data object.<br />
<br />
In order to make it easy to assign a stand-alone data object as an input to an algorithm, we introduced a set of convenience functions in VTK 6. Below is an example:<br />
<br />
<source lang="cpp"><br />
someFilter->SetInputData(aDataObject);<br />
</source><br />
<br />
Note that even though the following will compile, it will NOT create a pipeline connection and should not be used in place of SetInputConnection().<br />
<br />
<source lang="cpp"><br />
someFilter->SetInputData(someReader->GetOutput());<br />
</source><br />
<br />
Another advantage of decoupling data objects from pipeline objects is that developers no longer need to create shallow copies of inputs in order to use internal filters. Previously, this was required for an algorithm to function properly:<br />
<br />
<source lang="cpp"><br />
void MyFilter::RequestData(…)<br />
{<br />
vtkDataObject* input = inInfo->Get(vtkDataObject::DATA_OBJECT());<br />
vtkDataObject* copy = input->NewInstance();<br />
copy->ShallowCopy(input);<br />
this->InternalFilter->SetInput(copy);<br />
this->InternalFilter->Update();<br />
…<br />
}<br />
</source><br />
<br />
This can now be replaced with the following without any unexpected side effects:<br />
<br />
<source lang="cpp"><br />
void MyFilter::RequestData(…)<br />
{<br />
vtkDataObject* input = inInfo->Get(vtkDataObject::DATA_OBJECT());<br />
this->InternalFilter->SetInputData(input);<br />
this->InternalFilter->Update();<br />
…<br />
}<br />
</source><br />
<br />
Another advantage is that this change removes some circular references from the pipeline making it unnecessary to use the garbage collector. This should have a noticeable impact on the performance of VTK when using large pipelines.<br />
<br />
==Miscellaneous Changes==<br />
<br />
Certain classes in VTK 5 provided only a SetInput(vtkDataObject*) or similar method and not a SetInputConnection(vtkAlgorithmOutput*) (or similar) method. In all of these classes SetInput() was implemented by storing a reference to a data object. None of them were subclasses of vtkAlgorithm. We replaced all of these methods with SetInputData() as well as with SetInputConnection(), where SetInputData() does not setup a pipeline connection (hence the class does not update its input during execution) whereas SetInputConnection does (hence the class does update its input during execution). These classes include:<br />
<br />
* vtkParallelCoordinatesActor<br />
* vtkTkRenderWidget<br />
* vtkEncodedGradientEstimator<br />
* vtkGPUVolumeRayCastMapper (no longer updates “TransformedInput”)<br />
* vtkPKdTree<br />
* vtkBarChartActor<br />
* vtkCaptionActor2D<br />
* vtkCubeAxesActor2D<br />
* vtkGridTransform<br />
* vtkLegendBoxActor<br />
* vtkPieChartActor<br />
* vtkSpiderPlotActor<br />
* vtkXYPlotActor<br />
* vtk3DWidget<br />
* vtkBalloonRepresentation<br />
* vtkCheckerboardRepresentation<br />
* vtkLogoRepresentation<br />
* vtkPolyDataSourceWidget<br />
* vtkSCurveSpline<br />
* vtkKdTree<br />
* vtkImplicitDataSet<br />
* vtkImplicitVolume<br />
* vtkKochanekSpline<br />
* vtkCardinalSpline<br />
<br />
In addition, we changed or removed a few algorithms that produced variable number of outputs. This is not supported in VTK 5 without the backwards compatibility layer. Such algorithms need to produce vtkMultiBlockDataSet instead. We removed vtkPLOT3DReader. Use vtkMultiBlockPLOT3DReader instead. We changed vtkProcrustesAlignmentFilter to produce a multi-block dataset as well as have one input port that accepts multiple connections.</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/VTK_6_Migration/vtkType_deprecations&diff=52185VTK/VTK 6 Migration/vtkType deprecations2013-04-08T16:59:10Z<p>Seanmcbride: Created page with "vtkType.h's VTK_LARGE_ID has been deprecated and renamed to VTK_ID_MAX. A VTK_ID_MIN was also added, which did not exist before. To update you code, simply find-replace all VTK..."</p>
<hr />
<div>vtkType.h's VTK_LARGE_ID has been deprecated and renamed to VTK_ID_MAX. A VTK_ID_MIN was also added, which did not exist before.<br />
<br />
To update you code, simply find-replace all VTK_LARGE_ID to VTK_ID_MAX.</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/VTK_6_Migration_Guide&diff=52184VTK/VTK 6 Migration Guide2013-04-08T16:56:10Z<p>Seanmcbride: Added 'vtkType deprecations' section</p>
<hr />
<div>[[VTK/VTK_6_Migration/Overview | Overview]]<br />
<br />
[[VTK/VTK_6_Migration/Replacement_of_SetInput | Replacement of SetInput() with SetInputData() and SetInputConnection()]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_GetProducerPort | Removal of GetProducerPort() from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_ GetPipelineInformation | Removal of GetPipelineInformation and GetExecutive from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_Update | Removal of Pipeline Update Methods from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_Execute | Removal of ExecuteInformation() and ExecuteData() from Algorithm Superclasses]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_SetExtentTranslator | Removal of SetExtentTranslator and GetExtentTranslator from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_CopyInformation | Removal of CopyInformation and CopyTypeSpecificInformation from vtkDataObject and vtkImageData]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_CopyInformationToPipeline | Removal of CopyInformationToPipeline and CopyInformationFromPipeline from vtkDataObject and sub-classes]]<br />
<br />
[[VTK/VTK_6_Migration/Removal_of_GetEstimatedMemorySize | Removal of GetEstimatedMemorySize() method from vtkDataObject and vtkImageData ]]<br />
<br />
[[VTK/VTK_6_Migration/Removal of SetWholeExtent | Removal of SetWholeExtent() from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal of ShouldIReleaseData | Removal of ShouldIReleaseData() and ReleaseDataFlag methods from vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Removal of Methods for Manipulating Update Extent | Removal of vtkDataObject Methods for Manipulating Update Extent]]<br />
<br />
[[VTK/VTK_6_Migration/Change to Crop | Change to Crop() in vtkDataObject]]<br />
<br />
[[VTK/VTK_6_Migration/Changes to Scalars Manipulation Functions | Changes to Scalars Manipulation Functions in vtkImageData]]<br />
<br />
[[VTK/VTK_6_Migration/Change to CopyOriginAndSpacingFromPipeline | Change to CopyOriginAndSpacingFromPipeline in vtkImageData]]<br />
<br />
[[VTK/VTK_6_Migration/Changes to SetAxisUpdateExtent | Changes to SetAxisUpdateExtent and GetAxisUpdateExtent in vtkImageData]]<br />
<br />
[[VTK/VTK_6_Migration/Change to AllocateOutputData | Change to AllocateOutputData() in vtkImageAlgorithm]]<br />
<br />
[[VTK/VTK_6_Migration/Changes to vtkProcrustesAlignmentFilter | Changes to vtkProcrustesAlignmentFilter]]<br />
<br />
[[VTK/VTK_6_Migration/Removal of vtkPlot3DReader | Removal of vtkPlot3DReader]]<br />
<br />
[[VTK/VTK_6_Migration/vtkType deprecations | vtkType deprecations]]</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK&diff=52183VTK2013-04-08T16:52:43Z<p>Seanmcbride: minor rename</p>
<hr />
<div><center>http://public.kitware.com/images/logos/vtk-logo2.jpg</center><br />
<br /><br />
The Visualization ToolKit (VTK) is an open source, freely available software system for 3D computer graphics, image processing, and visualization used by thousands of researchers and developers around the world. VTK consists of a C++ class library, and several interpreted interface layers including Tcl/Tk, Java, and Python. Professional support and products for VTK are provided by Kitware, Inc. ([http://www.kitware.com www.kitware.com]) VTK supports a wide variety of visualization algorithms including scalar, vector, tensor, texture, and volumetric methods; and advanced modeling techniques such as implicit modelling, 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.<br />
<br />
<br />
== Learning VTK ==<br />
If you want to learn how to use or develop VTK, please see [[VTK/Learning_VTK | Learning VTK]]<br />
<br />
== Building VTK ==<br />
* Where can I [http://vtk.org/get-software.php download VTK]?<br />
<br />
* Where can I download a tarball of the [http://vtk.org/files/nightly/vtkNightlyDocHtml.tar.gz nightly HTML documentation]?<br />
<br />
* How do I build the [[VTK/BuildingDoxygen|Doxygen documentation]]?<br />
<br />
* [[VTK/Git|Using Git for VTK development]]<br />
<br />
* [[VTK/GitMSBuild|Using Git and MSBuild to build VTK]]<br />
<br />
* [[VTK/PythonDevelopment|Setting up a Python Development Environment using Eclipse/Pydev]]<br />
<br />
* [[VTK/Build parameters | Build parameters]]<br />
<br />
* [[Making Development Environment without compiling source distribution]]<br />
<br />
* [[VTK/Building/VisualStudio | Building VTK with Visual Studio]]<br />
<br />
== Extending VTK ==<br />
<br />
* Where can I get [[VTK Datasets]]?<br />
<br />
* [[VTK Classes|User-Contributed Classes]]<br />
<br />
* [[VTK Coding Standards]] <br />
<br />
* [[VTK/Commit_Guidelines|VTK Commit Guidelines]]<br />
<br />
* [[VTK Patch Procedure]] -- merge requests for the current release branch<br />
<br />
* [[VTK Scripts|Extending VTK with Scripts]]<br />
<br />
== Projects/ Tools that use VTK == <br />
<br />
* [[VTK Tools|VTK-Based Tools and Applications]]<br />
<br />
* What are some [[VTK Projects|projects using VTK]]?<br />
<br />
== Troubleshooting ==<br />
<br />
* [[VTK FAQ|Frequently asked questions (FAQ)]]<br />
<br />
* [[VTK OpenGL|Common OpenGL troubles]]<br />
<br />
== Miscellaneous ==<br />
* [[VTK Related Job Opportunities|VTK Related Job Opportunities]]<br />
<br />
* [[VTK/Third Party Library Patrol | VTK 3rd Party Library Patrol]]<br />
<br />
* [[VTK/Meeting Minutes | Meeting Minutes]]<br />
<br />
== Summary of Changes ==<br />
<br />
==== VTK 5.0 ====<br />
<br />
* [[VTK/Tutorials/New_Pipeline | New Pipeline]]<br />
* [[VTKWidgets | VTK Widget Redesign]]<br />
<br />
==== VTK 5.2 ====<br />
<br />
* [[VTK/Java Wrapping | VTK Java Wrapping]]<br />
* [[VTK/Composite Data Redesign | Composite Data Redesign]]<br />
* [[VTK Shaders | VTK Shaders]]<br />
* [[VTKShaders | Shaders in VTK]]<br />
* [[VTK/VTKMatlab | VTK with Matlab]]<br />
* [[VTK/Time_Support | VTK Time support]]<br />
* [[VTK/Graph Layout | VTK Graph Layout]]<br />
* [[VTK/Depth_Peeling | VTK Depth Peeling]]<br />
* [[VTK/Using_JRuby | Using VTK with JRuby]]<br />
* [[VTK/Painters | Painters]]<br />
<br />
==== VTK 5.4 ====<br />
<br />
* [[VTK 5.4 Release Planning]]<br />
* [[VTK/Cray XT3 Compilation| Cray XT3 Compilation]]<br />
* [[VTK/Geovis vision toolkit | Geospatial and vision visualization support ]]<br />
<br />
==== VTK 5.6 ====<br />
<br />
* [[VTK/MultiPass_Rendering | VTK Multi-Pass Rendering]]<br />
* [[VTK/Multicore and Streaming | Multicore and Streaming]]<br />
* [[VTK/statistics | Statistics]]<br />
* [[VTK/Array Refactoring | Array Refactoring]]<br />
* [[VTK/3DConnexion Devices Support | 3DConnexion Devices Support]]<br />
* [[VTK/Charts | New Charts API]]<br />
* [[VTK/New CellPicker | New Cell Picker and Volume Picking (start Nov 2010, finish Feb 2010)]]<br />
<br />
==== VTK 5.8 ====<br />
<br />
* [[VTK/Polyhedron_Support | Polyhedron cells and MVC Interpolation]]<br />
* [http://visimp.cs.unc.edu/2010/10/26/reeb-graphs/ Reeb Graphs]<br />
* [[VTK/Closed Surface Clipping | Clipping of closed surfaces (start Mar 26, 2010, finish Apr 22, 2010)]]<br />
* [[VTK/Wrapper Update 2010 | New wrappers (start Apr 28, 2010)]]<br />
* [[VTK/Image Stencil Improvements | Improved image stencil support (start Nov 3, 2010)]]<br />
* [[VTK/MNI File Formats | MNI file formats]]<br />
* [[VTK/Release580 New Classes | List of New Classes]]<br />
<br />
==== VTK 5.10 ====<br />
<br />
* [[VTK/improved unicode support | Change unicode readers/writers to register as codecs (finished Oct 29 2010)]]<br />
* [[VTK/Image Rendering Classes | New image rendering classes (start Dec 15 2010, finish Mar 15 2011)]]<br />
* [[VTK/Image Interpolators | Image interpolators (start Jun 20 2011, finish Aug 31 2011)]]<br />
* [[VTK/GSoC | Projects from Google Summer of Code 2011]]<br />
* [[VTK/Release5100 New Classes | List of new classes in 5.10]]<br />
<br />
==== VTK 6.0 (pending) ====<br />
<br />
* [[VTK/VTK_6_Migration_Guide | VTK 6 API Migration Guide]]<br />
* [[VTK/Build_System_Migration | VTK 6 (build system) Migration Guide]]<br />
* [[VTK/Remove_VTK_4_Compatibility | Remove VTK 4 compatibility layer from pipeline]]<br />
* [[VTK/Modularization_Proposal | Modularization]]<br />
* [[VTK/Remove_BTX_ETX | Remove BTX/ETX markers from VTK code]]<br />
* [[VTK/Remove_vtkTemporalDataSet | Temporal support changes]]<br />
* [[VTK/Composite_data_changes | Composite data structure changes ]]<br />
<br />
== News ==<br />
<br />
=== Development Process ===<br />
The VTK Community is [[VTK/Managing_the_Development_Process | upgrading its development process]]. We are doing this in response to the continuing and rapid growth of the toolkit. A VTK Architecture Review Board [[VTK/Architecture_Review_Board |VTK ARB]] is being put in place to provide strategic guidance to the community, and individuals are being identified as leaders in various VTK subsystems.<br />
<br />
Have a question or topic for the ARB to discuss about the future of VTK? First, please bring the topic to the [http://public.kitware.com/mailman/listinfo/vtk-developers VTK developers mailing list]. If the issue is not resolved there or needs further planning or direction, you may [[VTK/ARB/Meetings#Potential Topics|enter a suggested topic for discussion]].<br />
<br />
* [[Proposed Changes to VTK | Proposed Changes to VTK]]<br />
<br />
===[[VTK/NextGen|VTK NextGen]]=== <br />
We have started collecting works in progress as well as future ideas at [[VTK/NextGen|NextGen]]. Please add anything you are working on, would like to collaborate on, or would like to see in the future of VTK!<br />
<br />
== Wrapping ==<br />
<br />
* [[VTK/Wrappers | Wrapping Tools]]<br />
<br />
* [[VTK/Java Wrapping|Java]]<br />
** [[VTK/Java Code Samples|Java code samples]]<br />
* [[VTK/Python Wrapping FAQ|Python]]<br />
** [[VTK/Python Wrapper Enhancement|Python wrapper enhancements]]<br />
* [[VTK/CSharp/ActiViz.NET|CSharp/ActiViz.NET]]<br />
** [[VTK/Examples/CSharp|CSharp/ActiViz.NET code samples]]<br />
* [[VTK/CSharp/ComingSoon|CSharp/ComingSoon]]<br />
<br />
== Developers Corner ==<br />
[[VTK/Developers Corner|Developers Corner]]<br />
<br />
<!-- <br />
== External Links ==<br />
dead link *[http://zorayasantos.tripod.com/vtk_csharp_examples VTK examples in C#] (Visual Studio 5.0 and .NET 2.0)<br />
--><br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK_Coding_Standards&diff=51803VTK Coding Standards2013-03-14T18:01:23Z<p>Seanmcbride: VTK is C++03, not C++98</p>
<hr />
<div>==General Coding Standards==<br />
We only have a few coding standards but they have proved very useful.<br />
<br />
* We only put one public class per file. Some classes have helper classes that they use, but these are not accessible to the user.<br />
<br />
* Every class, macro, etc starts with either vtk or VTK, this avoids name clashes with other libraries. Classes should all start with vtk and macros or constants can start with either.<br />
<br />
* Class names and file names are the same. This makes it easier to find the correct file for a specific class.<br />
<br />
* We only use alphanumeric characters in names, [a-zA-z0-9]. So names like Extract_Surface are not welcome. We use capitalization to indicate words within a name. For example ExtractVectorTopology could be an instance variable. If it were a class it would be called vtkExtractVectorTopology. We capitalize the first letter of a name (excluding any preceding vtk). For local variables almost anything goes. Ideally we would suggest using same convention as instance variables except start their names with a lower case letter. e.g. extractVectorSurface.<br />
<br />
* We try to always spell out a name and not use abbreviations. This leads to longer names but it makes using the software easier because you know that the SetRasterFontRange method will always be called that, not SetRFRange or SetRFontRange or SetRFR. When the name includes a natural abbreviation such as OpenGL, we keep the abbreviation and capitalize the abbreviated letters.<br />
<br />
* We try to keep all instance variables protected. The user and application developer should access instance variables through Set/Get methods. To aid in this there are a number of macros defined in vtkSetGet.h that can be used. They expand into inline functions that Set/Get the instance variable and invoke a Modified() method if the value has changed.<br />
<br />
* Use "this" inside of methods even though C++ doesn't require you to. This really seems to make the code more readable because it disambiguates between instance variables and local or global variables. It also disambiguates between member functions and other functions.<br />
<br />
* Make sure your code compiles without any warnings with -Wall and -O2 (with gcc and clang).<br />
<br />
* The indentation style can be characterized as the "indented brace" style. Indentations are two spaces, and the curly brace (scope delimiter) is placed on the following line and indented along with the code (i.e., the curly brace lines up with the code). Example:<br />
<br />
if (this->Locator == locator)<br />
{<br />
return;<br />
}<br />
for (i = 0; i < this->Source->GetNumberOfPoints(); i++)<br />
{<br />
p1 = this->Source->GetPoint(i);<br />
[...]<br />
}<br />
<br />
* The header file of the class should include only the superclass's header file. If you do not, the header test run as part of the VTK dashboard will report an error. If any other includes are absolutely necessary, include comment at each one describing why it should be included:<br />
<br />
#include "vtkKWWindow.h"<br />
#include "vtkClientServerID.h" // Needed for InteractorID<br />
#include "vtkPVConfig.h" // Needed for PARAVIEW_USE_LOOKMARKS<br />
<br />
* Avoid using vtkSetObjectMacro since it will require including the header file of another class. Use the vtkCxxSetObjectMacro instead. For example:<br />
<br />
// Class declaration: <br />
// Description:<br />
// Set/Get the array used to store the visibility flags.<br />
virtual void SetVisibilityById(vtkUnsignedCharArray* vis);<br />
<br />
// Cxx file<br />
vtkCxxSetObjectMacro(vtkStructuredVisibilityConstraint,<br />
VisibilityById,<br />
vtkUnsignedCharArray);<br />
<br />
* All subclasses of vtkObject should include a PrintSelf() method that prints all publicly accessible ivars. For example:<br />
<br />
void vtkObject::PrintSelf(ostream& os, vtkIndent indent)<br />
{<br />
os << indent << "Debug: " << (this->Debug ? "On\n" : "Off\n");<br />
os << indent << "Modified Time: " << this->GetMTime() << "\n";<br />
this->Superclass::PrintSelf(os, indent);<br />
os << indent << "Registered Events: ";<br />
if ( this->SubjectHelper )<br />
{<br />
os << endl;<br />
this->SubjectHelper->PrintSelf(os,indent.GetNextIndent());<br />
}<br />
else<br />
{<br />
os << "(none)\n";<br />
}<br />
}<br />
<br />
* All subclasses of vtkObject should include a type macro in their class declaration. For example:<br />
<br />
class VTKCOMMONDATAMODEL_EXPORT vtkBox : public vtkImplicitFunction<br />
{<br />
public:<br />
vtkTypeMacro(vtkBox, vtkImplicitFunction);<br />
void PrintSelf(ostream& os, vtkIndent indent);<br />
...<br />
}<br />
<br />
* Do not use 'id' as a variable name in public headers as it is a reserved word in Objective-C++<br />
<br />
* Long smart pointer definitions should break after the equals sign and have two spaces preceding the next line<br />
<br />
vtkSmartPointer<vtkXMLPolyDataWriter> writer =<br />
vtkSmartPointer<vtkXMLPolyDataWriter>::New();<br />
<br />
* Prefer the use of vtkNew when the variable would be classically treated as a stack variable<br />
<br />
vtkNew<vtkXMLPolyDataWriter> writer;<br />
<br />
===C++ standard ===<br />
<br />
* VTK is written in C++03. Language/library features introduced in C++11 cannot be used.<br />
* Code must be valid C++03 and C++11. (They are mostly backwards compatible, but not entirely. ex: the 'auto' keyword changed meaning in C++11.)<br />
<br />
===STL usage in VTK===<br />
<br />
* STL usage in the Common modules (vtkCommonCore, vtkCommonDataModel etc):<br />
** STL is for implementation, not interface. STL references should be contained in a .cxx class or the private section of the .h header file<br />
** Use the PIMPL idiom to forward reference/contain STL classes in classes. Historically, STL was big, fat, and slow to compile so we do not want to include STL headers in any .h files that are included in public VTK header files in the vtkCommon modules<br />
<br />
* STL usage is permitted in all non Common modules<br />
** It should be used sparingly where it makes sense and there is not an appropriate VTK class<br />
** std::string is now preferred over vtkStdString in API<br />
** STL use should use the PIMPL idiom if it does not add the to API/is not useful for inheritance<br />
<br />
* General notes on STL use in VTK<br />
** Use the std:: namespace to refer to STL classes and functions (except for iostreams as mentioned below)<br />
** For an example of STL usage, see the [[VTK FAQ#Can I use STL with VTK?|VTK FAQ]].<br />
** If you do need to include STL files within a VTK header, you must add a comment after it so that the automated repository commit checks will accept your changes:<br />
#include <vector> // STL Header <additional Comment here><br />
<br />
* When using anything declared in iostream, do not use std::. Examples include cerr, cout, ios...<br />
** Do not include the iostream header. It is already included<br />
<br />
== Common Pitfalls ==<br />
<br />
=== Set method in constructor ===<br />
<br />
<tt>Set</tt> methods defined with <tt>vtkSetMacro</tt> cannot be used in the default constructor to initialize ivars because the first line of a <tt>Set</tt> method is to compare the current value of the ivar with the value in argument. As at this point (in the constructor), the ivar is not initialized yet, the comparison happens against an uninitialized value.<br />
<br />
valgrind will detect this kind of fault.<br />
<br />
For this reason, <b>in the constructor, the value of an ivar has to be initialized directly with the assignment operator</b> not through a <tt>Set</tt> method defined with <tt>vtkSetMacro</tt>.<br />
<br />
Example:<br />
<pre><br />
class vtkFoo : public vtkObject<br />
{<br />
public:<br />
...<br />
vtkGetMacro(X,int);<br />
vtkSetMacro(X,int);<br />
...<br />
protected:<br />
vtkFoo();<br />
int X;<br />
...<br />
};<br />
<br />
vtkFoo::vtkFoo<br />
{<br />
this->SetX(12); // neh<br />
}<br />
<br />
vtkFoo::vtkFoo<br />
{<br />
this->X=12; // good<br />
}<br />
</pre><br />
<br />
The issue looks pretty obvious in an isolated example like the one shown above. Sometimes it can also happen with an indirect call:<br />
<br />
<pre><br />
void vtkFoo::SetXToZero()<br />
{<br />
this->SetX(0);<br />
}<br />
<br />
vtkFoo::vtkFoo<br />
{<br />
this->SetXToZero(); // neh<br />
}<br />
</pre><br />
<br />
<br />
{{VTK/Template/Footer}}<br />
<br />
==Documentation Standards==<br />
===Remaining questions===<br />
* Where do default values go (with the set/get functions or with the variable definition?)<br />
<br />
===Standard Set/GetMacros===<br />
The documentation style for this type of pair is very straight forward. There MUST be a single //Description for the pair and a brief description of the variable that is being set/get.<br />
<source lang="cpp"><br />
// Description:<br />
// Set / get the sharpness of decay of the splats. This is the<br />
// exponent constant in the Gaussian equation. Normally this is<br />
// a negative value.<br />
vtkSetMacro(ExponentFactor,double);<br />
vtkGetMacro(ExponentFactor,double);<br />
</source><br />
<br />
===Set/GetVectorMacros===<br />
The documentation style for vector macros is to name each of the resulting variables. For example<br />
<source lang="cpp"><br />
// Description:<br />
// Set/Get DrawValue. This is the value that is used when filling data<br />
// or drawing lines.<br />
vtkSetVector4Macro(DrawColor, double);<br />
vtkGetVector4Macro(DrawColor, double);<br />
</source><br />
<br />
produces in the doxygen:<br />
<br />
<source lang="cpp"><br />
virtual void SetDrawColor (double, double, double, double)<br />
</source><br />
<br />
We must therefore name the variables in the description, like<br />
<source lang="cpp"><br />
// Description:<br />
// Set/Get the color which is used to draw shapes in the image. The parameters are SetDrawColor(red, green, blue, alpha)<br />
vtkSetVector4Macro(DrawColor, double);<br />
vtkGetVector4Macro(DrawColor, double);<br />
</source><br />
<br />
===Set/GetMacros + Boolean===<br />
There must be a single description for this triple of macros. For example:<br />
<source lang="cpp"><br />
// Description:<br />
// Turn on/off the generation of elliptical splats.<br />
vtkSetMacro(NormalWarping,int);<br />
vtkGetMacro(NormalWarping,int);<br />
vtkBooleanMacro(NormalWarping,int);<br />
</source><br />
<br />
===SetClamp/GetMacros===<br />
The description must describe the valid range of values.<br />
<source lang="cpp"><br />
// Description:<br />
// Should the data with value 0 be ignored? Valid range (0, 1).<br />
vtkSetClampMacro(IgnoreZero, int, 0, 1);<br />
vtkGetMacro(IgnoreZero, int);<br />
</source><br />
<br />
== Testing Standards ==<br />
<br />
* When adding a new concrete class, a test should also be added in <br />
...VTK/Package/Testing/Cxx/<br />
<br />
* The name of the file for the test should be ClassName.cxx where the name of the class is vtkClassName.<br />
<br />
* Each test should call several functions, each as short as possible, to exercise a specific functionality of the class. 1,000 lines in main() is very hard to maintain...<br />
<br />
* The "main()" function of the test file must be called TestClassName(int, char*[])<br />
<br />
===Questions===<br />
* Do we bother covering deprecated classes?<br />
* Is there a way to mark deprecated classes as deprecated so they do not show up on the coverage dashboards?<br />
* What is our target coverage percentage? 70%?<br />
* How to test abstract classes?<br />
* Can we create a system that checks for the existence of a test file for every concrete class? This would be a great place to start to improve coverage.<br />
* When should a new "test prefix" be started? By adding tests to a list like this:<br />
<br />
CREATE_TEST_SOURCELIST(''Array''Tests ArrayCxxTests.cxx<br />
<br />
they show up when running ctest as:<br />
<br />
Start 33: ''Array''-TestArrayBool<br />
<br />
* If arguments are not required, should you use<br />
TestName(int vtkNotUsed(argc), char *vtkNotUsed(argv)[])<br />
or<br />
TestName(int, char*[])</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK_Coding_Standards&diff=51802VTK Coding Standards2013-03-14T17:31:00Z<p>Seanmcbride: Added section about C++ standard</p>
<hr />
<div>==General Coding Standards==<br />
We only have a few coding standards but they have proved very useful.<br />
<br />
* We only put one public class per file. Some classes have helper classes that they use, but these are not accessible to the user.<br />
<br />
* Every class, macro, etc starts with either vtk or VTK, this avoids name clashes with other libraries. Classes should all start with vtk and macros or constants can start with either.<br />
<br />
* Class names and file names are the same. This makes it easier to find the correct file for a specific class.<br />
<br />
* We only use alphanumeric characters in names, [a-zA-z0-9]. So names like Extract_Surface are not welcome. We use capitalization to indicate words within a name. For example ExtractVectorTopology could be an instance variable. If it were a class it would be called vtkExtractVectorTopology. We capitalize the first letter of a name (excluding any preceding vtk). For local variables almost anything goes. Ideally we would suggest using same convention as instance variables except start their names with a lower case letter. e.g. extractVectorSurface.<br />
<br />
* We try to always spell out a name and not use abbreviations. This leads to longer names but it makes using the software easier because you know that the SetRasterFontRange method will always be called that, not SetRFRange or SetRFontRange or SetRFR. When the name includes a natural abbreviation such as OpenGL, we keep the abbreviation and capitalize the abbreviated letters.<br />
<br />
* We try to keep all instance variables protected. The user and application developer should access instance variables through Set/Get methods. To aid in this there are a number of macros defined in vtkSetGet.h that can be used. They expand into inline functions that Set/Get the instance variable and invoke a Modified() method if the value has changed.<br />
<br />
* Use "this" inside of methods even though C++ doesn't require you to. This really seems to make the code more readable because it disambiguates between instance variables and local or global variables. It also disambiguates between member functions and other functions.<br />
<br />
* Make sure your code compiles without any warnings with -Wall and -O2 (with gcc and clang).<br />
<br />
* The indentation style can be characterized as the "indented brace" style. Indentations are two spaces, and the curly brace (scope delimiter) is placed on the following line and indented along with the code (i.e., the curly brace lines up with the code). Example:<br />
<br />
if (this->Locator == locator)<br />
{<br />
return;<br />
}<br />
for (i = 0; i < this->Source->GetNumberOfPoints(); i++)<br />
{<br />
p1 = this->Source->GetPoint(i);<br />
[...]<br />
}<br />
<br />
* The header file of the class should include only the superclass's header file. If you do not, the header test run as part of the VTK dashboard will report an error. If any other includes are absolutely necessary, include comment at each one describing why it should be included:<br />
<br />
#include "vtkKWWindow.h"<br />
#include "vtkClientServerID.h" // Needed for InteractorID<br />
#include "vtkPVConfig.h" // Needed for PARAVIEW_USE_LOOKMARKS<br />
<br />
* Avoid using vtkSetObjectMacro since it will require including the header file of another class. Use the vtkCxxSetObjectMacro instead. For example:<br />
<br />
// Class declaration: <br />
// Description:<br />
// Set/Get the array used to store the visibility flags.<br />
virtual void SetVisibilityById(vtkUnsignedCharArray* vis);<br />
<br />
// Cxx file<br />
vtkCxxSetObjectMacro(vtkStructuredVisibilityConstraint,<br />
VisibilityById,<br />
vtkUnsignedCharArray);<br />
<br />
* All subclasses of vtkObject should include a PrintSelf() method that prints all publicly accessible ivars. For example:<br />
<br />
void vtkObject::PrintSelf(ostream& os, vtkIndent indent)<br />
{<br />
os << indent << "Debug: " << (this->Debug ? "On\n" : "Off\n");<br />
os << indent << "Modified Time: " << this->GetMTime() << "\n";<br />
this->Superclass::PrintSelf(os, indent);<br />
os << indent << "Registered Events: ";<br />
if ( this->SubjectHelper )<br />
{<br />
os << endl;<br />
this->SubjectHelper->PrintSelf(os,indent.GetNextIndent());<br />
}<br />
else<br />
{<br />
os << "(none)\n";<br />
}<br />
}<br />
<br />
* All subclasses of vtkObject should include a type macro in their class declaration. For example:<br />
<br />
class VTKCOMMONDATAMODEL_EXPORT vtkBox : public vtkImplicitFunction<br />
{<br />
public:<br />
vtkTypeMacro(vtkBox, vtkImplicitFunction);<br />
void PrintSelf(ostream& os, vtkIndent indent);<br />
...<br />
}<br />
<br />
* Do not use 'id' as a variable name in public headers as it is a reserved word in Objective-C++<br />
<br />
* Long smart pointer definitions should break after the equals sign and have two spaces preceding the next line<br />
<br />
vtkSmartPointer<vtkXMLPolyDataWriter> writer =<br />
vtkSmartPointer<vtkXMLPolyDataWriter>::New();<br />
<br />
* Prefer the use of vtkNew when the variable would be classically treated as a stack variable<br />
<br />
vtkNew<vtkXMLPolyDataWriter> writer;<br />
<br />
===C++ standard ===<br />
<br />
* VTK is written in C++98. Language/library features introduced in C++03 and C++11 cannot be used.<br />
* Code must be valid C++98, C++03, and C++11. (Each revision is mostly backwards compatible, but not entirely. ex: the 'auto' keyword changed meanings in C++11.)<br />
<br />
===STL usage in VTK===<br />
<br />
* STL usage in the Common modules (vtkCommonCore, vtkCommonDataModel etc):<br />
** STL is for implementation, not interface. STL references should be contained in a .cxx class or the private section of the .h header file<br />
** Use the PIMPL idiom to forward reference/contain STL classes in classes. Historically, STL was big, fat, and slow to compile so we do not want to include STL headers in any .h files that are included in public VTK header files in the vtkCommon modules<br />
<br />
* STL usage is permitted in all non Common modules<br />
** It should be used sparingly where it makes sense and there is not an appropriate VTK class<br />
** std::string is now preferred over vtkStdString in API<br />
** STL use should use the PIMPL idiom if it does not add the to API/is not useful for inheritance<br />
<br />
* General notes on STL use in VTK<br />
** Use the std:: namespace to refer to STL classes and functions (except for iostreams as mentioned below)<br />
** For an example of STL usage, see the [[VTK FAQ#Can I use STL with VTK?|VTK FAQ]].<br />
** If you do need to include STL files within a VTK header, you must add a comment after it so that the automated repository commit checks will accept your changes:<br />
#include <vector> // STL Header <additional Comment here><br />
<br />
* When using anything declared in iostream, do not use std::. Examples include cerr, cout, ios...<br />
** Do not include the iostream header. It is already included<br />
<br />
== Common Pitfalls ==<br />
<br />
=== Set method in constructor ===<br />
<br />
<tt>Set</tt> methods defined with <tt>vtkSetMacro</tt> cannot be used in the default constructor to initialize ivars because the first line of a <tt>Set</tt> method is to compare the current value of the ivar with the value in argument. As at this point (in the constructor), the ivar is not initialized yet, the comparison happens against an uninitialized value.<br />
<br />
valgrind will detect this kind of fault.<br />
<br />
For this reason, <b>in the constructor, the value of an ivar has to be initialized directly with the assignment operator</b> not through a <tt>Set</tt> method defined with <tt>vtkSetMacro</tt>.<br />
<br />
Example:<br />
<pre><br />
class vtkFoo : public vtkObject<br />
{<br />
public:<br />
...<br />
vtkGetMacro(X,int);<br />
vtkSetMacro(X,int);<br />
...<br />
protected:<br />
vtkFoo();<br />
int X;<br />
...<br />
};<br />
<br />
vtkFoo::vtkFoo<br />
{<br />
this->SetX(12); // neh<br />
}<br />
<br />
vtkFoo::vtkFoo<br />
{<br />
this->X=12; // good<br />
}<br />
</pre><br />
<br />
The issue looks pretty obvious in an isolated example like the one shown above. Sometimes it can also happen with an indirect call:<br />
<br />
<pre><br />
void vtkFoo::SetXToZero()<br />
{<br />
this->SetX(0);<br />
}<br />
<br />
vtkFoo::vtkFoo<br />
{<br />
this->SetXToZero(); // neh<br />
}<br />
</pre><br />
<br />
<br />
{{VTK/Template/Footer}}<br />
<br />
==Documentation Standards==<br />
===Remaining questions===<br />
* Where do default values go (with the set/get functions or with the variable definition?)<br />
<br />
===Standard Set/GetMacros===<br />
The documentation style for this type of pair is very straight forward. There MUST be a single //Description for the pair and a brief description of the variable that is being set/get.<br />
<source lang="cpp"><br />
// Description:<br />
// Set / get the sharpness of decay of the splats. This is the<br />
// exponent constant in the Gaussian equation. Normally this is<br />
// a negative value.<br />
vtkSetMacro(ExponentFactor,double);<br />
vtkGetMacro(ExponentFactor,double);<br />
</source><br />
<br />
===Set/GetVectorMacros===<br />
The documentation style for vector macros is to name each of the resulting variables. For example<br />
<source lang="cpp"><br />
// Description:<br />
// Set/Get DrawValue. This is the value that is used when filling data<br />
// or drawing lines.<br />
vtkSetVector4Macro(DrawColor, double);<br />
vtkGetVector4Macro(DrawColor, double);<br />
</source><br />
<br />
produces in the doxygen:<br />
<br />
<source lang="cpp"><br />
virtual void SetDrawColor (double, double, double, double)<br />
</source><br />
<br />
We must therefore name the variables in the description, like<br />
<source lang="cpp"><br />
// Description:<br />
// Set/Get the color which is used to draw shapes in the image. The parameters are SetDrawColor(red, green, blue, alpha)<br />
vtkSetVector4Macro(DrawColor, double);<br />
vtkGetVector4Macro(DrawColor, double);<br />
</source><br />
<br />
===Set/GetMacros + Boolean===<br />
There must be a single description for this triple of macros. For example:<br />
<source lang="cpp"><br />
// Description:<br />
// Turn on/off the generation of elliptical splats.<br />
vtkSetMacro(NormalWarping,int);<br />
vtkGetMacro(NormalWarping,int);<br />
vtkBooleanMacro(NormalWarping,int);<br />
</source><br />
<br />
===SetClamp/GetMacros===<br />
The description must describe the valid range of values.<br />
<source lang="cpp"><br />
// Description:<br />
// Should the data with value 0 be ignored? Valid range (0, 1).<br />
vtkSetClampMacro(IgnoreZero, int, 0, 1);<br />
vtkGetMacro(IgnoreZero, int);<br />
</source><br />
<br />
== Testing Standards ==<br />
<br />
* When adding a new concrete class, a test should also be added in <br />
...VTK/Package/Testing/Cxx/<br />
<br />
* The name of the file for the test should be ClassName.cxx where the name of the class is vtkClassName.<br />
<br />
* Each test should call several functions, each as short as possible, to exercise a specific functionality of the class. 1,000 lines in main() is very hard to maintain...<br />
<br />
* The "main()" function of the test file must be called TestClassName(int, char*[])<br />
<br />
===Questions===<br />
* Do we bother covering deprecated classes?<br />
* Is there a way to mark deprecated classes as deprecated so they do not show up on the coverage dashboards?<br />
* What is our target coverage percentage? 70%?<br />
* How to test abstract classes?<br />
* Can we create a system that checks for the existence of a test file for every concrete class? This would be a great place to start to improve coverage.<br />
* When should a new "test prefix" be started? By adding tests to a list like this:<br />
<br />
CREATE_TEST_SOURCELIST(''Array''Tests ArrayCxxTests.cxx<br />
<br />
they show up when running ctest as:<br />
<br />
Start 33: ''Array''-TestArrayBool<br />
<br />
* If arguments are not required, should you use<br />
TestName(int vtkNotUsed(argc), char *vtkNotUsed(argv)[])<br />
or<br />
TestName(int, char*[])</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK_Coding_Standards&diff=51801VTK Coding Standards2013-03-14T17:16:56Z<p>Seanmcbride: clarify that -Wall and -O2 apply to gcc and clang</p>
<hr />
<div>==General Coding Standards==<br />
We only have a few coding standards but they have proved very useful.<br />
<br />
* We only put one public class per file. Some classes have helper classes that they use, but these are not accessible to the user.<br />
<br />
* Every class, macro, etc starts with either vtk or VTK, this avoids name clashes with other libraries. Classes should all start with vtk and macros or constants can start with either.<br />
<br />
* Class names and file names are the same. This makes it easier to find the correct file for a specific class.<br />
<br />
* We only use alphanumeric characters in names, [a-zA-z0-9]. So names like Extract_Surface are not welcome. We use capitalization to indicate words within a name. For example ExtractVectorTopology could be an instance variable. If it were a class it would be called vtkExtractVectorTopology. We capitalize the first letter of a name (excluding any preceding vtk). For local variables almost anything goes. Ideally we would suggest using same convention as instance variables except start their names with a lower case letter. e.g. extractVectorSurface.<br />
<br />
* We try to always spell out a name and not use abbreviations. This leads to longer names but it makes using the software easier because you know that the SetRasterFontRange method will always be called that, not SetRFRange or SetRFontRange or SetRFR. When the name includes a natural abbreviation such as OpenGL, we keep the abbreviation and capitalize the abbreviated letters.<br />
<br />
* We try to keep all instance variables protected. The user and application developer should access instance variables through Set/Get methods. To aid in this there are a number of macros defined in vtkSetGet.h that can be used. They expand into inline functions that Set/Get the instance variable and invoke a Modified() method if the value has changed.<br />
<br />
* Use "this" inside of methods even though C++ doesn't require you to. This really seems to make the code more readable because it disambiguates between instance variables and local or global variables. It also disambiguates between member functions and other functions.<br />
<br />
* Make sure your code compiles without any warnings with -Wall and -O2 (with gcc and clang).<br />
<br />
* The indentation style can be characterized as the "indented brace" style. Indentations are two spaces, and the curly brace (scope delimiter) is placed on the following line and indented along with the code (i.e., the curly brace lines up with the code). Example:<br />
<br />
if (this->Locator == locator)<br />
{<br />
return;<br />
}<br />
for (i = 0; i < this->Source->GetNumberOfPoints(); i++)<br />
{<br />
p1 = this->Source->GetPoint(i);<br />
[...]<br />
}<br />
<br />
* The header file of the class should include only the superclass's header file. If you do not, the header test run as part of the VTK dashboard will report an error. If any other includes are absolutely necessary, include comment at each one describing why it should be included:<br />
<br />
#include "vtkKWWindow.h"<br />
#include "vtkClientServerID.h" // Needed for InteractorID<br />
#include "vtkPVConfig.h" // Needed for PARAVIEW_USE_LOOKMARKS<br />
<br />
* Avoid using vtkSetObjectMacro since it will require including the header file of another class. Use the vtkCxxSetObjectMacro instead. For example:<br />
<br />
// Class declaration: <br />
// Description:<br />
// Set/Get the array used to store the visibility flags.<br />
virtual void SetVisibilityById(vtkUnsignedCharArray* vis);<br />
<br />
// Cxx file<br />
vtkCxxSetObjectMacro(vtkStructuredVisibilityConstraint,<br />
VisibilityById,<br />
vtkUnsignedCharArray);<br />
<br />
* All subclasses of vtkObject should include a PrintSelf() method that prints all publicly accessible ivars. For example:<br />
<br />
void vtkObject::PrintSelf(ostream& os, vtkIndent indent)<br />
{<br />
os << indent << "Debug: " << (this->Debug ? "On\n" : "Off\n");<br />
os << indent << "Modified Time: " << this->GetMTime() << "\n";<br />
this->Superclass::PrintSelf(os, indent);<br />
os << indent << "Registered Events: ";<br />
if ( this->SubjectHelper )<br />
{<br />
os << endl;<br />
this->SubjectHelper->PrintSelf(os,indent.GetNextIndent());<br />
}<br />
else<br />
{<br />
os << "(none)\n";<br />
}<br />
}<br />
<br />
* All subclasses of vtkObject should include a type macro in their class declaration. For example:<br />
<br />
class VTKCOMMONDATAMODEL_EXPORT vtkBox : public vtkImplicitFunction<br />
{<br />
public:<br />
vtkTypeMacro(vtkBox, vtkImplicitFunction);<br />
void PrintSelf(ostream& os, vtkIndent indent);<br />
...<br />
}<br />
<br />
* Do not use 'id' as a variable name in public headers as it is a reserved word in Objective-C++<br />
<br />
* Long smart pointer definitions should break after the equals sign and have two spaces preceding the next line<br />
<br />
vtkSmartPointer<vtkXMLPolyDataWriter> writer =<br />
vtkSmartPointer<vtkXMLPolyDataWriter>::New();<br />
<br />
* Prefer the use of vtkNew when the variable would be classically treated as a stack variable<br />
<br />
vtkNew<vtkXMLPolyDataWriter> writer;<br />
<br />
===STL usage in VTK===<br />
<br />
* STL usage in the Common modules (vtkCommonCore, vtkCommonDataModel etc):<br />
** STL is for implementation, not interface. STL references should be contained in a .cxx class or the private section of the .h header file<br />
** Use the PIMPL idiom to forward reference/contain STL classes in classes. Historically, STL was big, fat, and slow to compile so we do not want to include STL headers in any .h files that are included in public VTK header files in the vtkCommon modules<br />
<br />
* STL usage is permitted in all non Common modules<br />
** It should be used sparingly where it makes sense and there is not an appropriate VTK class<br />
** std::string is now preferred over vtkStdString in API<br />
** STL use should use the PIMPL idiom if it does not add the to API/is not useful for inheritance<br />
<br />
* General notes on STL use in VTK<br />
** Use the std:: namespace to refer to STL classes and functions (except for iostreams as mentioned below)<br />
** For an example of STL usage, see the [[VTK FAQ#Can I use STL with VTK?|VTK FAQ]].<br />
** If you do need to include STL files within a VTK header, you must add a comment after it so that the automated repository commit checks will accept your changes:<br />
#include <vector> // STL Header <additional Comment here><br />
<br />
* When using anything declared in iostream, do not use std::. Examples include cerr, cout, ios...<br />
** Do not include the iostream header. It is already included<br />
<br />
== Common Pitfalls ==<br />
<br />
=== Set method in constructor ===<br />
<br />
<tt>Set</tt> methods defined with <tt>vtkSetMacro</tt> cannot be used in the default constructor to initialize ivars because the first line of a <tt>Set</tt> method is to compare the current value of the ivar with the value in argument. As at this point (in the constructor), the ivar is not initialized yet, the comparison happens against an uninitialized value.<br />
<br />
valgrind will detect this kind of fault.<br />
<br />
For this reason, <b>in the constructor, the value of an ivar has to be initialized directly with the assignment operator</b> not through a <tt>Set</tt> method defined with <tt>vtkSetMacro</tt>.<br />
<br />
Example:<br />
<pre><br />
class vtkFoo : public vtkObject<br />
{<br />
public:<br />
...<br />
vtkGetMacro(X,int);<br />
vtkSetMacro(X,int);<br />
...<br />
protected:<br />
vtkFoo();<br />
int X;<br />
...<br />
};<br />
<br />
vtkFoo::vtkFoo<br />
{<br />
this->SetX(12); // neh<br />
}<br />
<br />
vtkFoo::vtkFoo<br />
{<br />
this->X=12; // good<br />
}<br />
</pre><br />
<br />
The issue looks pretty obvious in an isolated example like the one shown above. Sometimes it can also happen with an indirect call:<br />
<br />
<pre><br />
void vtkFoo::SetXToZero()<br />
{<br />
this->SetX(0);<br />
}<br />
<br />
vtkFoo::vtkFoo<br />
{<br />
this->SetXToZero(); // neh<br />
}<br />
</pre><br />
<br />
<br />
{{VTK/Template/Footer}}<br />
<br />
==Documentation Standards==<br />
===Remaining questions===<br />
* Where do default values go (with the set/get functions or with the variable definition?)<br />
<br />
===Standard Set/GetMacros===<br />
The documentation style for this type of pair is very straight forward. There MUST be a single //Description for the pair and a brief description of the variable that is being set/get.<br />
<source lang="cpp"><br />
// Description:<br />
// Set / get the sharpness of decay of the splats. This is the<br />
// exponent constant in the Gaussian equation. Normally this is<br />
// a negative value.<br />
vtkSetMacro(ExponentFactor,double);<br />
vtkGetMacro(ExponentFactor,double);<br />
</source><br />
<br />
===Set/GetVectorMacros===<br />
The documentation style for vector macros is to name each of the resulting variables. For example<br />
<source lang="cpp"><br />
// Description:<br />
// Set/Get DrawValue. This is the value that is used when filling data<br />
// or drawing lines.<br />
vtkSetVector4Macro(DrawColor, double);<br />
vtkGetVector4Macro(DrawColor, double);<br />
</source><br />
<br />
produces in the doxygen:<br />
<br />
<source lang="cpp"><br />
virtual void SetDrawColor (double, double, double, double)<br />
</source><br />
<br />
We must therefore name the variables in the description, like<br />
<source lang="cpp"><br />
// Description:<br />
// Set/Get the color which is used to draw shapes in the image. The parameters are SetDrawColor(red, green, blue, alpha)<br />
vtkSetVector4Macro(DrawColor, double);<br />
vtkGetVector4Macro(DrawColor, double);<br />
</source><br />
<br />
===Set/GetMacros + Boolean===<br />
There must be a single description for this triple of macros. For example:<br />
<source lang="cpp"><br />
// Description:<br />
// Turn on/off the generation of elliptical splats.<br />
vtkSetMacro(NormalWarping,int);<br />
vtkGetMacro(NormalWarping,int);<br />
vtkBooleanMacro(NormalWarping,int);<br />
</source><br />
<br />
===SetClamp/GetMacros===<br />
The description must describe the valid range of values.<br />
<source lang="cpp"><br />
// Description:<br />
// Should the data with value 0 be ignored? Valid range (0, 1).<br />
vtkSetClampMacro(IgnoreZero, int, 0, 1);<br />
vtkGetMacro(IgnoreZero, int);<br />
</source><br />
<br />
== Testing Standards ==<br />
<br />
* When adding a new concrete class, a test should also be added in <br />
...VTK/Package/Testing/Cxx/<br />
<br />
* The name of the file for the test should be ClassName.cxx where the name of the class is vtkClassName.<br />
<br />
* Each test should call several functions, each as short as possible, to exercise a specific functionality of the class. 1,000 lines in main() is very hard to maintain...<br />
<br />
* The "main()" function of the test file must be called TestClassName(int, char*[])<br />
<br />
===Questions===<br />
* Do we bother covering deprecated classes?<br />
* Is there a way to mark deprecated classes as deprecated so they do not show up on the coverage dashboards?<br />
* What is our target coverage percentage? 70%?<br />
* How to test abstract classes?<br />
* Can we create a system that checks for the existence of a test file for every concrete class? This would be a great place to start to improve coverage.<br />
* When should a new "test prefix" be started? By adding tests to a list like this:<br />
<br />
CREATE_TEST_SOURCELIST(''Array''Tests ArrayCxxTests.cxx<br />
<br />
they show up when running ctest as:<br />
<br />
Start 33: ''Array''-TestArrayBool<br />
<br />
* If arguments are not required, should you use<br />
TestName(int vtkNotUsed(argc), char *vtkNotUsed(argv)[])<br />
or<br />
TestName(int, char*[])</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/VTK_6_Migration/Overview&diff=51775VTK/VTK 6 Migration/Overview2013-03-12T17:38:13Z<p>Seanmcbride: Added note about dropping old compilers and OSes.</p>
<hr />
<div>= Summary =<br />
<br />
One of the main goals of the pipeline re-architecture between VTK 4 and 5 was to 1) move the execution logic from data and process (algorithm) objects to a new set of classes called executives. This was to enable easy modification and extension of the pipeline (execution) code as well as to 2) separate data and execution “models” in order to simplify the code for both. The changes between VTK 4 and 5 achieved the first goal fairly well but did not tackle the second goal in order to preserve backwards compatibility with VTK 4. The work described herein has two major goals:<br />
<br />
# To remove the VTK 4 backwards compatibility layer introduced in VTK 5 in order to simplify the toolkit.<br />
# To carry the work started in VTK 5 to its logical conclusion by completely separating data and executions models<br />
<br />
This work comes at a cost: many of the changes described here are not backwards compatible with VTK 4 and some of them are not backwards compatible with VTK 5. In this document, we summarize the changes introduced as part of this work as well as provide guidance in migrating existing code forward. <br />
<br />
= Overview of Changes =<br />
<br />
The changes introduced as part of this work can be classified under a few major categories:<br />
<br />
# Removal of VTK 4 backwards compatibility superclasses: This includes vtkProcessObject, vtkSource and all of their subclasses. These classes were changed in VTK 5 in order to provide backwards compatibility. In VTK 6, all pipeline modules should subclass from vtkAlgorithm or one of its subclasses.<br />
# Removal of the pipeline meta-data API from vtkDataObject: As of VTK 5, the main containers of all pipeline meta-data and heavy-data are vtkInformation objects that represent input and output information for algorithms. Data objects should no longer be used to store meta-data (e.g. Whole Extent, Update Extent etc.). The vtkDataObject API for pipeline meta-data was kept for backwards compatibility to VTK 4 and was removed as part of this work.<br />
# Removal of data objects’ dependency on the pipeline code (algorithms and executives): The aims of this change are to simplify data object classes and to allow for the separation of data and execution model libraries as part of the ongoing modularization effort. This change causes a few incompatibilities explained in detail below.<br />
# Removal of support for old compilers and operating systems. Visual Studio 7.0 and older, Borland 5.6 and older, and Mac OS X 10.4 and older are no longer supported.<br />
<br />
= Changes in Detail =<br />
<br />
== Removal of VTK 4 Backwards Compatibility Superclasses ==<br />
<br />
The changes to the pipeline and pipeline modules introduced in VTK are explained in detail in a PDF document in VTK’s source code distribution: VTK/Utilities/Upgrading/TheNewVTKPipeline.pdf. If you are not familiar with these changes and find that your code stopped compiling due to changes described in this section, we recommend that you review that document first. It described in more detail the changes to pipeline modules and how to migrate to VTK 5.<br />
<br />
In order to the transition to the VTK 5 pipeline implementation as smoothly as possible, VTK 5 introduced a set of backwards compatibility classes. These included modified versions of previous algorithm superclasses including vtkProcessObject, vtkSource, vtkXXXSource (where XXX represents various data types) and vtkXXXToYYYFilter (where XXX and YYY are various data types). VTK 6 removes all of these classes and requires that all pipeline modules subclass from vtkAlgorithm or one of its subclasses and use the RequestInformation / RequestUpdateExtent / RequestData API rather than ExecutionInformation / PropagateUpdateExtent / Execute API. Below is a full list of backwards compatibility classes that were removed in VTK 6. If your code fails to compile because it refers to any of these classes, it is time to migrate to the VTK 5 API.<br />
<br />
* Filtering/vtkDataObjectSource<br />
* Filtering/vtkDataSetSource<br />
* Filtering/vtkDataSetToDataSetFilter<br />
* Filtering/vtkDataSetToImageFilter<br />
* Filtering/vtkDataSetToPolyDataFilter<br />
* Filtering/vtkDataSetToStructuredGridFilter<br />
* Filtering/vtkDataSetToStructuredPointsFilter<br />
* Filtering/vtkDataSetToUnstructuredGridFilter<br />
* Filtering/vtkImageInPlaceFilter<br />
* Filtering/vtkImageMultipleInputFilter<br />
* Filtering/vtkImageMultipleInputOutputFilter<br />
* Filtering/vtkImageSource<br />
* Filtering/vtkImageToImageFilter<br />
* Filtering/vtkImageTwoInputFilter<br />
* Filtering/vtkPointSetSource<br />
* Filtering/vtkPointSetToPointSetFilter<br />
* Filtering/vtkPolyDataSource<br />
* Filtering/vtkPolyDataToPolyDataFilter<br />
* Filtering/vtkProcessObject<br />
* Filtering/vtkRectilinearGridSource<br />
* Filtering/vtkRectilinearGridToPolyDataFilter<br />
* Filtering/vtkSource<br />
* Filtering/vtkStructuredGridSource<br />
* Filtering/vtkStructuredGridToPolyDataFilter<br />
* Filtering/vtkStructuredGridToStructuredGridFilter<br />
* Filtering/vtkStructuredPointsSource<br />
* Filtering/vtkStructuredPointsToPolyDataFilter<br />
* Filtering/vtkStructuredPointsToStructuredPointsFilter<br />
* Filtering/vtkStructuredPointsToUnstructuredGridFilter<br />
* Filtering/vtkUnstructuredGridSource<br />
* Filtering/vtkUnstructuredGridToPolyDataFilter<br />
* Filtering/vtkUnstructuredGridToUnstructuredGridFilter<br />
* FilteringvtkStructuredPointsToUnstructuredGridFilter<br />
* FilteringvtkUnstructuredGridToUnstructuredGridFilter<br />
* Imaging/vtkImageSpatialFilter<br />
<br />
== Removal of All Pipeline Meta-Data API from vtkDataObject== <br />
<br />
Examples of pipeline meta-data include WholeExtent, UpdateExtent, MaximumNumberOfPieces, UpdateNumberOfPieces, UpdatePiece, UpdateGhostLevel, ScalarType and NumberOfScalarComponents. In VTK 5, this meta-data is represented by vtkInformation keys such as vtkStreamingDemandDriven::WHOLE_EXTENT() and vtkStreamingDemandDrivenPipeline::UPDATE_EXTENT() and flow up and down the pipeline through input and output information objects passed to ProcessRequest (hence to RequestInformation, RequestUpdateExtent and RequestData). In VTK 4, this was achieved using vtkDataObjects and the vtkDataObject API (methods such as Set/GetWholeExtent, Set/GetUpdateExtent etc.). VTK 5 maintained this API as well as the associated vtkDataObject data members. The Executives had the responsibility of synching vtkDataObject data members with data in input and output information objects. The code to achieve this was hard to maintain and fragile. Furthermore, developers were often confused by the API to obtain pipeline specific meta-data (such as WholeExtent – the extent of the entire image available from a source or a reader) and data specific meta-data (such as Extent – the extent of the image data currently in memory). For example, we encountered the following in several places in VTK code as well as in other applications that used VTK:<br />
<br />
<source lang="cpp"><br />
vtkImageData* image = vtkImageData::New();<br />
int extent[6] = {0, 10, 0, 10, 0, 10};<br />
image->SetExtent(extent);<br />
image->SetUpdateExtent(extent);<br />
image->SetWholeExtent(extent);<br />
image->AllocateScalars();<br />
</source><br />
<br />
The correct implementation (which only uses SetExtent) was not clear to many developers and they chose the “safe” route of setting everything related to Extent to the same value – which is not really safe since it is a bug.<br />
<br />
VTK 6 removes all pipeline meta-data API from data object and requires the use of the appropriate information keys to create, modify and read pipeline meta-data. Refer to the Appendix for a full list of methods removed from vtkDataObject.<br />
<br />
== Removal of Data Objects’ Dependency on the Pipeline ==<br />
<br />
The final set of changes introduced as part of this work remove the dependency of vtkDataObject and its subclasses on the pipeline objects (executives and algorithms) completely decoupling the VTK “data model” from the VTK “execution model”. This has two major advantages:<br />
<br />
* Support for modularization: With these changes, it will be possible to create a small, self-contained library that only includes support for core classes and data model classes. This will enable developers to leverage VTK’s data model in their applications without significant code bloat.<br />
* Simplification of data object and pipeline execution APIs: These changes eliminate a significant amount of API duplication between algorithms and executives simplifying the VTK API. For example, to update (i.e. to force the execution of an) algorithm, the developer now has to access one method: vtkAlgorithm:Update() rather than several distributed among data objects and algorithms.<br />
<br />
Some of the changes introduced to remove this dependency are transparent to all but advanced users/developers of VTK. Others impact many developers that use VTK. The first of these is that all pipeline execution API was removed from vtkDataObject. Therefore, code similar to the following will not compile:<br />
<br />
<source lang="cpp"><br />
vtkDataObject* dobj = someAlgorithm->GetOutput();<br />
dobj->Update();<br />
</source><br />
<br />
This needs to be replaced with the following<br />
<br />
<source lang="cpp"><br />
someAlgorithm->Update();<br />
</source><br />
<br />
The second backwards-incompatible change is probably the one that will impact the most code. In VTK 4, pipeline objects were connected as follows:<br />
<br />
<source lang="cpp"><br />
someFilter->SetInput(someReader->GetOutput());<br />
</source><br />
<br />
In VTK 5, this was changed to:<br />
<br />
<source lang="cpp"><br />
someFilter->SetInputConnection(someReader->GetOutputPort());<br />
</source><br />
<br />
However, the SetInput() and related methods were preserved for backwards compatibility. This method and all related functions, such as SetSource, were removed in VTK 6. The main reason behind this is that it is impossible to preserve this method while decoupling data objects from pipeline objects. In VTK 5, SetInput() was implemented under the hood using SetInputConnection() but this required access to the algorithm and its output port given a data object. In VTK 6, since the data object no longer has a reference to the algorithm that produced it, it is not possible to establish a pipeline connection given only a data object.<br />
<br />
In order to make it easy to assign a stand-alone data object as an input to an algorithm, we introduced a set of convenience functions in VTK 6. Below is an example:<br />
<br />
<source lang="cpp"><br />
someFilter->SetInputData(aDataObject);<br />
</source><br />
<br />
Note that even though the following will compile, it will NOT create a pipeline connection and should not be used in place of SetInputConnection().<br />
<br />
<source lang="cpp"><br />
someFilter->SetInputData(someReader->GetOutput());<br />
</source><br />
<br />
Another advantage of decoupling data objects from pipeline objects is that developers no longer need to create shallow copies of inputs in order to use internal filters. Previously, this was required for an algorithm to function properly:<br />
<br />
<source lang="cpp"><br />
void MyFilter::RequestData(…)<br />
{<br />
vtkDataObject* input = inInfo->Get(vtkDataObject::DATA_OBJECT());<br />
vtkDataObject* copy = input->NewInstance();<br />
copy->ShallowCopy(input);<br />
this->InternalFilter->SetInput(copy);<br />
this->InternalFilter->Update();<br />
…<br />
}<br />
</source><br />
<br />
This can now be replaced with the following without any unexpected side effects:<br />
<br />
<source lang="cpp"><br />
void MyFilter::RequestData(…)<br />
{<br />
vtkDataObject* input = inInfo->Get(vtkDataObject::DATA_OBJECT());<br />
this->InternalFilter->SetInputData(input);<br />
this->InternalFilter->Update();<br />
…<br />
}<br />
</source><br />
<br />
Another advantage is that this change removes some circular references from the pipeline making it unnecessary to use the garbage collector. This should have a noticeable impact on the performance of VTK when using large pipelines.<br />
<br />
==Miscellaneous Changes==<br />
<br />
Certain classes in VTK 5 provided only a SetInput(vtkDataObject*) or similar method and not a SetInputConnection(vtkAlgorithmOutput*) (or similar) method. In all of these classes SetInput() was implemented by storing a reference to a data object. None of them were subclasses of vtkAlgorithm. We replaced all of these methods with SetInputData() as well as with SetInputConnection(), where SetInputData() does not setup a pipeline connection (hence the class does not update its input during execution) whereas SetInputConnection does (hence the class does update its input during execution). These classes include:<br />
<br />
* vtkParallelCoordinatesActor<br />
* vtkTkRenderWidget<br />
* vtkEncodedGradientEstimator<br />
* vtkGPUVolumeRayCastMapper (no longer updates “TransformedInput”)<br />
* vtkPKdTree<br />
* vtkBarChartActor<br />
* vtkCaptionActor2D<br />
* vtkCubeAxesActor2D<br />
* vtkGridTransform<br />
* vtkLegendBoxActor<br />
* vtkPieChartActor<br />
* vtkSpiderPlotActor<br />
* vtkXYPlotActor<br />
* vtk3DWidget<br />
* vtkBalloonRepresentation<br />
* vtkCheckerboardRepresentation<br />
* vtkLogoRepresentation<br />
* vtkPolyDataSourceWidget<br />
* vtkSCurveSpline<br />
* vtkKdTree<br />
* vtkImplicitDataSet<br />
* vtkImplicitVolume<br />
* vtkKochanekSpline<br />
* vtkCardinalSpline<br />
<br />
In addition, we changed or removed a few algorithms that produced variable number of outputs. This is not supported in VTK 5 without the backwards compatibility layer. Such algorithms need to produce vtkMultiBlockDataSet instead. We removed vtkPLOT3DReader. Use vtkMultiBlockPLOT3DReader instead. We changed vtkProcrustesAlignmentFilter to produce a multi-block dataset as well as have one input port that accepts multiple connections.</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/Git&diff=44770VTK/Git2012-01-10T18:19:42Z<p>Seanmcbride: made 'revise' section more consistent with 'push' section, by each step being a different line</p>
<hr />
<div>__TOC__<br />
<br />
VTK version tracking and development is hosted by [http://git-scm.com Git].<br />
<br />
=Official Repository=<br />
<br />
One may browse the repository online using the [http://git.wiki.kernel.org/index.php/Gitweb Gitweb] interface at http://vtk.org/gitweb.<br />
<br />
==Cloning==<br />
<br />
These instructions assume a command prompt is available with <code>git</code> in the path.<br />
See our Git [[Git/Download|download instructions]] for help installing Git.<br />
<br />
One may clone the repository using [http://www.kernel.org/pub/software/scm/git/docs/git-clone.html git clone] through the native <code>git</code> protocol:<br />
<br />
$ git clone git://vtk.org/VTK.git VTK<br />
<br />
or through the (less efficient) <code>http</code> protocol:<br />
<br />
$ git clone http://vtk.org/VTK.git VTK<br />
<br />
All further commands work inside the local copy of the repository created by the clone:<br />
<br />
$ cd VTK<br />
<br />
For VTKData the URLs are<br />
<br />
git://vtk.org/VTKData.git<br />
http://vtk.org/VTKData.git<br />
<br />
For VTKLargeData the URLs are<br />
<br />
git://vtk.org/VTKLargeData.git<br />
http://vtk.org/VTKLargeData.git<br />
<br />
==Branches==<br />
<br />
At the time of this writing the repository has the following branches:<br />
<br />
* '''master''': Development (default)<br />
* '''release''': Release maintenance<br />
* '''nightly-master''': Follows '''master''', updated at 01:00 UTC<br />
* '''hooks''': Local commit hooks ([[Git/Hooks#Local|place]] in .git/hooks)<br />
<br />
Release branches converted from CVS have been artificially merged into master.<br />
Actual releases have tags named by the release version number.<br />
<br />
=Development=<br />
<br />
We provide here a brief introduction to '''VTK''' development with Git.<br />
See the [[Git/Resources|Resources]] page for further information such as Git tutorials.<br />
<br />
==Quick Start Guide==<br />
<br />
If you would like to get up and running quickly, we recommend you follow the [[VTK/Git/Simple|simple Git guide]]. It will guide you through getting your development environment setup, working on topic branches and merging your changes back into master.<br />
<br />
==Introduction==<br />
<br />
We require all commits in VTK to record valid author/committer name and email information.<br />
<br />
Use [http://www.kernel.org/pub/software/scm/git/docs/git-config.html git config] to introduce yourself to Git:<br />
<br />
$ git config --global user.name "Your Name"<br />
$ git config --global user.email "you@yourdomain.com"<br />
<br />
Note that "Your Name" is your ''real name'' (e.g. "John Doe", not "jdoe").<br />
While you're at it, optionally enable color output from Git commands:<br />
<br />
$ git config --global color.ui auto<br />
<br />
The <code>--global</code> option stores the configuration settings in <code>~/.gitconfig</code> in your home directory so that they apply to all repositories.<br />
<br />
On Linux/OS X or msysgit on Windows, the following script will perform several additional setup tasks:<br />
<br />
$ ./Utilities/SetupForDevelopment.sh<br />
<br />
This will instal local hooks, add a topic stage, and set up some useful Git aliases for gerrit and the topic stage.<br />
<br />
==Hooks==<br />
<br />
The '''hooks''' branch provides local commit hooks to be placed in <code>.git/hooks</code>.<br />
It is shared by many <code>public.kitware.com</code> repositories.<br />
<br />
See the general [[Git/Hooks|hooks]] information page to set up your local hooks.<br />
<br />
==Workflow==<br />
<br />
We have now moved to use a branchy workflow, [http://public.kitware.com/Wiki/Git/Workflow/Topic branchy workflow] based on topic branches. We do not have a next integration branch at this point, and so you should ignore any reference to that and merge straight to master. The next sections describes use of gerrit and the topic stage, [[VTK/Git/Simple|simplified guide]] can be followed using supplied scripts and aliases.<br />
<br />
==Gerrit==<br />
<br />
If you have a patch that you want to be considered for inclusion in VTK, you can submit it to [http://review.source.kitware.com/ gerrit]. To register on gerrit, use the following steps:<br />
<br />
# Get an [http://openid.net/get-an-openid/ OpenID]<br />
# Register at http://review.source.kitware.com using your OpenID (link in upper right)<br />
# Set all fields in your profile at http://review.source.kitware.com/#settings<br />
# Add your ssh public key at http://review.source.kitware.com/#settings,ssh-keys<br />
<br />
You will then be ready to submit patches. A typical patch for gerrit will be a topic branch that includes a single commit. If your branch has multiple commits you should use "git rebase -i" to squash the commits into a single commit, or if this is not reasonable, then consider pushing your branch to github or to some other external site for review. Your topic branch should be based on either the release or the master, depending on where you want it to go. An example workflow is as follows:<br />
<br />
{| border="0"<br />
!colspan=2|Gerrit Usage Summary<br />
|-<br />
|align="center"|<br />
'''Initial Setup:'''<br />
|<br />
$ git remote add gerrit USERNAME@review.source.kitware.com:VTK<br />
|-<br />
|align="center"|<br />
'''Create topic branch:'''<br />
|<br />
$ git checkout master<br />
$ git pull (i.e. get your local repository up-to-date)<br />
$ git checkout -b topic-branch-to-create<br />
|-<br />
|align="center"|<br />
'''Push to Gerrit:'''<br />
|<br />
$ edit files<br />
$ git add /path/to/newfile1 /path/to/newfile2<br />
$ git commit -a<br />
$ git gerrit-push (alias for git push gerrit HEAD:refs/for/master/topic-name)<br />
|-<br />
|align="center"|<br />
'''Revise a Gerrit topic:'''<br />
|<br />
$ edit files<br />
$ git add /path/to/editedfile1 /path/to/editedfile2<br />
$ git commit --amend<br />
$ verify that the commit log ends with the correct Change-Id<br />
$ git gerrit-push<br />
|-<br />
|align="center"|<br />
'''Squash commits:'''<br />
|<br />
$ git rebase -i HEAD~2 (number depends on number of commits to squash)<br />
$ verify that the commit log ends with the correct Change-Id<br />
$ git gerrit-push<br />
|-<br />
|align="center"|<br />
'''Merge topic into VTK:'''<br />
|<br />
$ git stage-push (alias for git push stage HEAD)<br />
$ git stage-merge (alias for ssh git@vtk.org stage VTK merge topic-name)<br />
|}<br />
<br />
To get your patch reviewed, go to [http://review.source.kitware.com/ http://review.source.kitware.com/] and add reviewers for your patch. Alternatively, you can post an email to the vtk-developers list asking for reviewers. If you do not have commit access for VTK, ask one of the reviewers to merge your topic into VTK.<br />
<br />
==Topic Stage==<br />
<br />
We provide a "[http://vtk.org/stage/VTK.git VTK Topic Stage]" repository to which developers may publish arbitrary topic branches and request automatic merges. To follow this workflow, you should have git version 1.7 or greater.<br />
<br />
The topic stage URLs are<br />
<br />
* <code>git://vtk.org/stage/VTK.git</code> (clone, fetch)<br />
* <code>http://vtk.org/stage/VTK.git</code> (clone, fetch, gitweb)<br />
* <code>git@vtk.org:stage/VTK.git</code> (push)<br />
<br />
See our [http://public.kitware.com/Wiki/Git/Workflow/Stage Topic Stage Workflow] documentation for general instructions.<br />
''(Currently VTK does not have a '''next''' branch. Just skip that part of the instructions and merge directly to master.)''<br />
When accessing the VTK stage, one may optionally substitute<br />
"<code>ssh git@vtk.org stage VTK ...</code>"<br />
for<br />
"<code>ssh git@public.kitware.com stage <repo> ...</code>"<br />
in the ssh command-line interface.<br />
<br />
{| border="0"<br />
!colspan=2|Stage Usage Summary<br />
|-<br />
|align="center"|<br />
'''Initial Setup:'''<br />
|<br />
$ git remote add stage git://vtk.org/stage/VTK.git<br />
$ git config remote.stage.pushurl git@vtk.org:stage/VTK.git<br />
|-<br />
|align="center"|<br />
'''Fetch Staged Topics:'''<br />
|<br />
$ git fetch stage --prune<br />
|-<br />
|align="center"|<br />
'''Create Local Topic:'''<br />
|<br />
$ git checkout -b ''topic-name'' origin/master<br />
$ edit files<br />
$ git commit<br />
|-<br />
|align="center"|<br />
'''Stage Current Topic:'''<br />
|<br />
$ git push stage HEAD<br />
|-<br />
|align="center"|<br />
'''Print Staged Topics:'''<br />
|<br />
$ ssh git@vtk.org stage VTK print<br />
|-<br />
|align="center"|<br />
'''Merge Staged Topic:'''<br />
|<br />
$ ssh git@vtk.org stage VTK merge ''topic-name''<br />
|-<br />
|align="center"|<br />
'''Check out Staged Topic:'''<br />
|<br />
$ git fetch stage<br />
$ git checkout -b ''topic-name'' remotes/stage/''topic-name''<br />
|-<br />
|align="center"|<br />
'''Abandon/Delete Staged Topic:'''<br />
|<br />
$ git push stage :''topic-name''<br />
<br />
|}<br />
<br />
If the merge attempt conflicts follow the printed instructions.<br />
<br />
==Github==<br />
<br />
The VTK repository is mirrored on github. Experimental branches that are not ready for staging can be published on github for review.<br />
<br />
The first step in creating a github branch is to create an account on github and make a fork of [http://github.com/Kitware/VTK http://github.com/Kitware/VTK]. Since this fork will be a mirror of the VTK master, there is no need to clone it on your local machine. Instead, you will just want to set github as an alternative remote in your existing local copy of the VTK git repository.<br />
<br />
To set github as an alternative remote, use the following commands:<br />
<br />
{| border="0"<br />
!colspan=2|Github Usage Summary<br />
|-<br />
|align="center"|<br />
'''Remote Setup:'''<br />
|<br />
$ git remote add github git@github.com:yourname/VTK.git<br />
$ git config remote.github.pushurl git@github.com:yourname/VTK.git<br />
|-<br />
|align="center"|<br />
'''Update the Remote:'''<br />
|<br />
# update from Kitware's master and push to github<br />
$ git pull<br />
$ git push github HEAD<br />
|-<br />
|align="center"|<br />
'''Push Branch to Github:'''<br />
|<br />
$ git checkout -b some-branch github/master<br />
# edit files and commit changes<br />
$ git push github HEAD<br />
|}<br />
<br />
The "update remote" step above should be done regularly on your master, in order to keep your github fork up-to-date with the VTK master. Do not use github's graphical interface for merging commits, it creates new commits by rebasing the commits you select against your VTK fork. These rebased commits will be very difficult to merge back into VTK master.<br />
<br />
The checkout command in the third step will automatically set github as the default remote for the new branch, but you still must specify "github HEAD" when you push or else you will push to the github master branch, instead of pushing to a new github branch. Also, since it bases the branch on your github fork, you should perform step 2 before creating the branch to make sure that your fork is up-to-date. This is just a suggestion, as it is always possible to rebase or merge at a later time.<br />
<br />
The default remotes for each of your branches are controlled by entries such as this in your .git/config file:<br />
<br />
[branch "my-branch-name"]<br />
remote = github<br />
merge = refs/heads/my-branch-name<br />
<br />
You can edit this file to make github the default remote and to set the remote branch name for your existing branches. Or you can always use "git push github HEAD" to push each branch to github, without changing the defaults.<br />
<br />
=Publishing=<br />
<br />
==Pushing==<br />
<br />
Authorized developers may publish work directly to <code>vtk.org/VTK.git</code> using Git's SSH protocol.<br />
To request access, fill out the [https://www.kitware.com/Admin/SendPassword.cgi Kitware Password] form.<br />
<br />
See the [[Git/Publish#Push_Access|push instructions]] for details.<br />
<br />
For VTK, configure the push URL:<br />
<br />
git config remote.origin.pushurl git@vtk.org:VTK.git<br />
<br />
For VTKData, configure the push URL:<br />
<br />
git config remote.origin.pushurl git@vtk.org:VTKData.git<br />
<br />
===Update Hook===<br />
<br />
The vtk.org repository has an <code>update</code> hook.<br />
When someone tries to push changes to the repository it checks the commits as documented [[Git/Hooks#update|here]].<br />
<br />
==Patches==<br />
<br />
Contributions of bug fixes and features are commonly produced by the community. Patches are a convenient method for managing such contributions.<br />
<br />
One may send patches after subscribing to our mailing list:<br />
<br />
* [http://www.vtk.org/mailman/listinfo/vtk-developers VTK Developers Mailing List]<br />
<br />
See our [[Git/Publish#Patches|patch instructions]] for details.<br />
<br />
= Troubleshooting =<br />
== fatal: The remote end hung up unexpectedly ==<br />
* If <tt>git push</tt> fails with "fatal: The remote end hung up unexpectedly", you probably forgot to set the push url with "git config" see [[#Pushing]].<br />
* if <tt>git pull</tt> or <tt>git fetch</tt> fails, you might be behind a firewall: try editing .git/config so that the urls start with http:// instead of git://<br />
<br />
== Restoring files locally ==<br />
Q: "I cloned the VTK repository. Now I "rm -rf Hybrid". How do I get it back?"<br><br />
A: git checkout Hybrid<br><br />
Q: "I modified a file locally. I want to revert it."<br><br />
A: git checkout myfile.cxx<br><br />
Q: "I want to get rid of all local changes in this directory and start clean."<br><br />
A: git checkout .<br />
<br />
=Resources=<br />
<br />
Additional information about Git may be obtained at sites listed [[Git/Resources|here]].</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=ITK/Gerrit/Reviewers&diff=33294ITK/Gerrit/Reviewers2010-10-26T16:28:05Z<p>Seanmcbride: added more info regarding me, Sean</p>
<hr />
<div>= Reviewers List =<br />
<br />
== From Gerrit ==<br />
<br />
* http://review.source.kitware.com/#admin,group,5<br />
<br />
== Explicit List ==<br />
<br />
* Alex. Gouaillard<br />
* Arnaud Gelas<br />
* Bill Lorensen<br />
* Brad King<br />
* Bradley Lowekamp<br />
* Casey Goodlett<br />
* Cory Quammen<br />
* Dan Mueller<br />
* Daniel Blezek<br />
* Gabe Hart<br />
* Gaëtan Lehmann<br />
* Hans J. Johnson<br />
* Jim Miller<br />
* Karthik Krishnan<br />
* Luis Ibanez<br />
* Marcus D. Hanwell<br />
* Mark Roden<br />
* Mathieu Malaterre<br />
* Wesley D. Turner<br />
* Xiaoxiao Liu<br />
* Kent Williams<br />
* Brian Avants<br />
* Sean McBride<br />
<br />
= Reviewer Expertise Index =<br />
<br />
<br />
== Architecture ==<br />
<br />
*Luis Ibanez<br />
<br />
== DICOM ==<br />
<br />
*Mathieu Malaterre<br />
*Mark Roden<br />
<br />
== Meshes ==<br />
<br />
* Arnaud Gelas<br />
* Alex Gouaillard<br />
* Luis Ibanez<br />
<br />
== QuadEdgeMesh ==<br />
<br />
*Arnaud Gelas<br />
*Alex Gouaillard<br />
<br />
== Modularization ==<br />
<br />
* Xiaoxiao Liu<br />
* Luis Ibanez<br />
<br />
== Level Sets ==<br />
<br />
*Arnaud Gelas<br />
<br />
== Image Filtering ==<br />
<br />
*Luis Ibanez<br />
*Dan Mueller<br />
*Wesley Turner<br />
<br />
== Image IO ==<br />
<br />
*Luis Ibanez<br />
*Bradley Lowekamp<br />
<br />
== Image Registration ==<br />
<br />
*Luis Ibanez<br />
*Dan Mueller<br />
*Brian Avants<br />
*Bradley Lowekamp<br />
*Xiaoxiao Liu<br />
*Casey Goodlett<br />
<br />
== Image Segmentation ==<br />
<br />
*Luis Ibanez<br />
*Dan Mueller<br />
*Xiaoxiao Liu<br />
*Cory Quammen<br />
*Wesley Turner<br />
<br />
== Streaming ==<br />
<br />
*Bradley Lowekamp<br />
<br />
== FEM ==<br />
<br />
*Brian Avants<br />
<br />
= Compilers =<br />
<br />
== Mingw (gcc version ?) ==<br />
<br />
* Bill Lorensen<br />
<br />
== VS 10 Express ==<br />
<br />
* Alex. Gouaillard ( +WindowsSDK7.1 for 64 bits compilation ) ( XP Pro, Win 7 )<br />
<br />
== VS 9 ==<br />
<br />
* Wesley Turner<br />
* Luis Ibanez<br />
<br />
== VS 8 ==<br />
<br />
* Luis Ibanez<br />
<br />
== llvm-gcc-4.2.1 ==<br />
<br />
* Kent Williams (Mac OS X, build 2326.10)<br />
* Sean McBride (Mac OS X, build 5658)<br />
<br />
== clang ==<br />
<br />
* Sean McBride (Mac OS X)<br />
<br />
== Gcc 4.4 ==<br />
<br />
* Luis Ibanez (Ubuntu 9.04)<br />
* Bill Lorensen (Fedora 13)<br />
* Kent Williams (Red Hat)<br />
<br />
== Gcc 4.2.1 ==<br />
<br />
* Cory Quammen (Mac OS X, build 5664)<br />
* Alex. Gouaillard (Mac OS X, build 5664)<br />
* Kent Williams (Mac OS X, build 5664)<br />
* Sean McBride (Mac OS X, build 5664)<br />
<br />
== Gcc 4.1 ==<br />
<br />
* Luis Ibanez (Debian)<br />
* Alex. Gouaillard (Ubuntu)<br />
<br />
== Gcc 4.0.1 ==<br />
<br />
* Kent Williams (Mac OS X, build 5664)<br />
<br />
== Gcc 3.4 ==<br />
<br />
* Luis Ibanez (Debian)<br />
* Kent Williams (Red Hat)<br />
<br />
= Tools =<br />
<br />
== KWStyle ==<br />
<br />
* Brad Davis<br />
* Julien Jomier<br />
* Hans Johnson<br />
* Brad Lowekamp<br />
<br />
== CMake / CTest / CPack ==<br />
<br />
* Dave Cole<br />
* Marcus D. Hanwell<br />
* Bill Hoffman<br />
* Brad King<br />
<br />
= Operating Systems =<br />
<br />
== Mac OS X ==<br />
<br />
* Sean McBride</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=ITK/Git&diff=25504ITK/Git2010-07-26T14:43:43Z<p>Seanmcbride: typo</p>
<hr />
<div>__TOC__<br />
<br />
ITK version tracking and development is hosted by [http://git-scm.com Git].<br />
<br />
=Official Repository=<br />
<br />
One may browse the repository online using the [http://git.wiki.kernel.org/index.php/Gitweb Gitweb] interface at http://itk.org/gitweb.<br />
<br />
==Cloning==<br />
<br />
One may clone the repository using [http://www.kernel.org/pub/software/scm/git/docs/git-clone.html git clone] through the native <code>git</code> protocol:<br />
<br />
$ git clone git://itk.org/ITK.git<br />
<br />
or through the (less efficient) <code>http</code> protocol:<br />
<br />
<pre><br />
$ git clone http://itk.org/ITK.git<br />
</pre><br />
<br />
All further commands work inside the local copy of the repository created by the clone:<br />
<br />
$ cd ITK<br />
<br />
If you want to run the tests you also need to clone the <code>Testing/Data</code> submodule:<br />
<br />
$ git submodule update --init<br />
<br />
For ITKApps the URLs are<br />
<br />
<pre><br />
git://itk.org/ITKApps.git<br />
http://itk.org/ITKApps.git<br />
</pre><br />
<br />
==Branches==<br />
<br />
At the time of this writing the repository has the following branches:<br />
<br />
* '''master''': Development (default)<br />
* '''nightly-master''': Follows '''master''', updated at 01:00 UTC<br />
* '''hooks''': Local commit hooks ([[Git/Hooks#Local|place]] in .git/hooks)<br />
* '''dashboard''': Dashboard script (see [[#Dashboard|below]])<br />
<br />
Release branches converted from CVS have been artificially merged into master.<br />
Actual releases have tags named by the release version number.<br />
<br />
=Development=<br />
<br />
We provide here a brief introduction to '''ITK''' development with Git.<br />
See the [[Git/Resources|Resources]] page for further information such as Git tutorials.<br />
<br />
==Introduction==<br />
<br />
We require all commits in ITK to record valid author/committer name and email information.<br />
Use [http://www.kernel.org/pub/software/scm/git/docs/git-config.html git config] to introduce yourself to Git:<br />
<br />
$ git config --global user.name "Your Name"<br />
$ git config --global user.email "you@yourdomain.com"<br />
<br />
Note that "Your Name" is your ''real name'' (e.g. "John Doe", not "jdoe").<br />
While you're at it, optionally enable color output from Git commands:<br />
<br />
$ git config --global color.ui auto<br />
<br />
If less displays strange characters and no color, your LESS environment variable may already be set. You can override the less options with:<br />
<br />
$ git config --global core.pager "less -FXRS"<br />
<br />
The <code>--global</code> option stores the configuration settings in <code>~/.gitconfig</code> in your home directory so that they apply to all repositories.<br />
<br />
==Hooks==<br />
<br />
The '''hooks''' branch provides local commit hooks to be placed in <code>.git/hooks</code>.<br />
It is shared by many <code>public.kitware.com</code> repositories.<br />
<br />
See the general [[Git/Hooks|hooks]] information page to set up your local hooks.<br />
<br />
==Workflow==<br />
<br />
We've chosen to approximate our previous CVS-based development workflow after the initial move to Git, at least while things get settled.<br />
The basic rule is to rebase your work on origin/master before pushing:<br />
<br />
git fetch origin<br />
git rebase origin/master<br />
<br />
or<br />
<br />
git pull --rebase<br />
<br />
The server will refuse your push if it contains any merges.<br />
Later we will move to a full [[Git/Workflow/Topic|branchy workflow]] based on topic branches.<br />
<br />
=Publishing=<br />
<br />
==Pushing==<br />
<br />
Authorized developers may publish work directly to <code>itk.org/ITK.git</code> using Git's SSH protocol.<br />
To request access, fill out the [https://www.kitware.com/Admin/SendPassword.cgi Kitware Password] form.<br />
<br />
See the [[Git/Publish#Push_Access|push instructions]] for details.<br />
<br />
For ITK, configure the push URL:<br />
<br />
git config remote.origin.pushurl git@itk.org:ITK.git<br />
<br />
For ITKApps, configure the push URL:<br />
<br />
git config remote.origin.pushurl git@itk.org:ITKApps.git<br />
<br />
===Update Hook===<br />
<br />
The itk.org repository has an <code>update</code> hook.<br />
When someone tries to push changes to the repository it checks the commits as documented [[Git/Hooks#update|here]].<br />
<br />
=Testing=<br />
<br />
==Dashboard==<br />
<br />
The [[#Branches| dashboard]] branch contains a dashboard client helper script.<br />
Use these commands to track it:<br />
<br />
$ mkdir -p ~/Dashboards/ITKScripts<br />
$ cd ~/Dashboards/ITKScripts<br />
$ git init<br />
$ git remote add -t dashboard origin git://itk.org/ITK.git<br />
$ git pull origin<br />
<br />
The <code>itk_common.cmake</code> script contains setup instructions in its top comments.<br />
Update the '''dashboard''' branch to get the latest version of this script by simply running<br />
<br />
$ git pull origin<br />
<br />
=Troubleshooting=<br />
<br />
==Firewall Blocks Port 9418==<br />
<br />
Some institutions have firewalls that block Git's native protocol port 9418.<br />
Use the "<code>url.<base>.insteadOf</code>" configuration option to map git URLs to http:<br />
<br />
<pre><br />
$ git config --global url.http://itk.org/.insteadOf git://itk.org/<br />
</pre><br />
<br />
This tells Git to translate URLs under the hood by replacing prefixes.<br />
After running these commands ''once'' in your home directory then you can just use the "<code>git://</code>" mentioned elsewhere on this page and git will use the http protocol automagically.<br />
<br />
=Resources=<br />
<br />
Additional information about Git may be obtained at sites listed [[Git/Resources|here]].</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=ITK/Release_Schedule&diff=25019ITK/Release Schedule2010-07-12T16:33:27Z<p>Seanmcbride: /* Valgrind Hunting Campaign */</p>
<hr />
<div>The next release is 3.20 scheduled for July 15 2010.<br />
<br />
== Release Life Cycle ==<br />
<br />
=== Last period for adding classes and features ===<br />
<br />
* New classes will be selected from good reviews from the Insight Journal<br />
* New features and new methods can be added during this period.<br />
<br />
=== Feature Freeze ===<br />
<br />
* Increase code coverage<br />
** address any UNTESTED files<br />
** address files with code coverage lower than 80%<br />
* Address Run-time memory issues<br />
** Purify reports<br />
** Valgrind reports<br />
<br />
=== CVS Tagging ===<br />
<br />
The repository is tagged by using two tags, one for the reference, and another for the branch.<br />
<br />
=== Posting Tarballs ===<br />
<br />
* Tarballs are posted to SourceForge<br />
* Tarballs are linked from the ITK Download<br />
<br />
== Release 3.20 Schedule ==<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Release Number !! Start Date !! End Date<br />
|-<br />
| Bug triage || May 1 2010 || May 5 2010<br />
|-<br />
| CVS Tagging || July 14 2010 || July 14, 2010<br />
|-<br />
| Testing tarballs || July 15 2010 || July 15 2010<br />
|-<br />
| Posting tarballs || July 15 2010 || July 15 2010<br />
|}<br />
<br />
=== Code Coverage Campaign ===<br />
<br />
* Gabe Hart (Kitware) worked on several of the ITK files with the Lowest code coverage and raised their code coverage above 80%, of course uncovering bugs and design flaws in the process.<br />
<br />
=== Valgrind Hunting Campaign ===<br />
<br />
* Sophie Chen (Kitware ) worked on removing five (out of the 33 valgrind errors in ITK). We have since, lost the Nightly Valgrind builds, so this needs to be restored.<br />
<br />
== Release 3.22 Schedule ==<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Release Number !! Start Date !! End Date<br />
|-<br />
| Bug triage || Oct 1 2010 || Oct 5 2010<br />
|-<br />
| CVS Tagging || Oct 14 2010 || Oct 14, 2010<br />
|-<br />
| Testing tarballs || Oct 15 2010 || Oct 15 2010<br />
|-<br />
| Posting tarballs || Oct 15 2010 || Oct 15 2010<br />
|}<br />
<br />
== Check-list for Moving Code from IJ to Review and from Review ==<br />
<br />
=== For IJ Articles To Review ===<br />
* Responsible developer should add a review '''before''' moving into local copy of Review. Please provide authors with feedback regarding changes that were made to conform to ITK style/documentation etc.<br />
<br />
=== For Adding Images to Input or Baseline ===<br />
<br />
* Images should be '''SMALL'''.<br />
** The source tree is not an image database, but a source code repository.<br />
** Adding an image larger than 50Kb should be justified by a discussion in the Developers list<br />
** Make sure that you use the "cvs add -kb" option when adding binary files to the CVS repository.<br />
* Regression images should not use Analyze format unless the test is for the AnalyzeImageIO and related classes.<br />
* Images should use non-trivial Metadata.<br />
** Origin should be different form zeros<br />
** Spacing should be different from ones, and it should be anisotropic<br />
** Direction should be different from Identity<br />
<br />
=== For Moving Code From Review ===<br />
* At least one independent (other than contributor) should sign off on the API<br />
* Coverage should be as close to 100% as possible.<br />
** and never lower than 90%.<br />
** For example, itkTransformIOBase.cxx is only at 63% coverage. Should be easily fixed by adding a Print() to one of the tests.<br />
<br />
=== For All ===<br />
* Check all comments for proper English<br />
* Should pass KWStyle. IJ articles should be checked with KWStyle before checking into repository.<br />
* Should pass PrintSelf. IJ articles should pass PrintSelf check before checking into repository.<br />
* ITK_EXPORT should appear in each class definition. This triggers the PrintSelf checker.<br />
* Replace itkGetMacro with itkGetConstMacro.<br />
* Header file should contain Insight Journal citation<br />
** Using the "handle" link.<br />
* Use vcl verions of all transcendental functions.<br />
** For example, itkGaborKernelFunction used sin() and cos() rather than vcl_sin() and vcl_cos().<br />
* Progress should be present for all filters. Use itk::SimplerFilterWatcher to exercise progress and PrintSelfs.<br />
* When appropriate, class should handle image directions. Tests should use non-default values for origin, spacing and dimension.<br />
** GaborImageSource did not provide methods to set/get directions.<br />
* Regression tests names should when possible have the same name as the test.<br />
* Exceptions should be descriptive and provide as much information as possible<br />
* Member data should be private with access if required through Get methods.<br />
<br />
== Release History ==<br />
* [[ITK_Previous_Releases|ITK Release History]]</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=ITK_Release_4/Wish_List&diff=24990ITK Release 4/Wish List2010-07-12T14:33:10Z<p>Seanmcbride: </p>
<hr />
<div>The wish list is provided by members of the ITK development community.<br />
These requests are not necessarily included in the NLM-funded ITKv4 and ITKv4 A2D2 contracts.<br />
== Oriented Images ==<br />
* Support ND image in N+1 dimension<br />
** 2D image can have an origin specified in 3D, thus a series of 2D images is not always Z-aligned<br />
** Support ND images in M dimensions where M > N.<br />
* All images are oriented - remove concept of an un-oriented image<br />
* Check use of orientation throughout ITK<br />
* Support re-orientation of ND oriented images<br />
** Using anything other than 3D images won't compile with itkOrientedImageFilter<br />
<br />
** Spatial Objects<br />
** Meshes<br />
* Suggestions<br />
** [[ITK_Release_4.0_Orientation_by_Kent]]<br />
** [[ITK_Release_4.0_Orientation_by_Torsten]]<br />
** [[ITK_Release_4.0_Orientation_by_Michael]]<br />
** [http://wiki.na-mic.org/Wiki/index.php/Complex_Image_Set Some notes on complex image acquisitions by Steve and Greg]<br />
<br />
== Image Representation ==<br />
* Allow the use of strides that are not equal to the image width<br />
** Would ease the collaboration of ITK with opencv<br />
** Would allow the use of sse operations<br />
** Might be considered redundant with correct use of image regions but is not since GetLargestPossibleRegion should correspond to the image width and not its stride<br />
* Drop the itk::Image::GetBufferPointer() method<br />
** This method has been many time described as a problem to implement new image layouts.<br />
** As expressed above, we need however to be able to use the memory held by ITK images within other libraries. This could potentially be done by making itk::Image be only a base class that has no knowledge of the memory layout and by implementing different image subclasses.<br />
* Consider replacing ImportImageContainer by std::vector or using std::vector to implement it<br />
** This would give STL iterators that operate on the whole image literally for free and make it easy to use a lot of algorithms implemented in STL and BOOST<br />
** [http://www.boost.org/doc/libs/1_39_0/libs/gil/doc/index.html Boost gil] also offers a compelling alternative for memory management of images. Unfortunately it seems to be still focused on 2D<br />
** '''Lorensen:''' ITK images are n-dimensional. The current iterator design enables that required functionality. If I recall, stl iterators were considered but did not meet the n-d requirements.<br />
* See [http://hdl.handle.net/10380/3068 Alternative Memory Models for ITK Images] on the Insight Journal for an initial implementation of such ideas<br />
* Discuss a proper way of handling dynamic images (2D+t is not really 3D and 3D+t is difficult in terms of memory management)<br />
<br />
== Statistics ==<br />
* Complete statistics refactoring (see NAMIC sandbox)<br />
<br />
== FEM Meshes ==<br />
* [[Refactoring itk::FEM framework - V4]]<br />
* Consolidate FEM Meshes and ITK Meshes<br />
<br />
== Backward compatibility and cleanup ==<br />
* Clean-up CMake Vars ==<br />
** See proposal [[ITK_CMake_Style|HERE]].<br />
* Remove Deprecated Features<br />
** Functions that have been deprecated (and appropriately marked as such) for more than 3 releases should be removed.<br />
* Modify the itkSetMacro to use a const reference argument, i.e. #define itkSetMacro(name,type) virtual void Set##name (const type & _arg)<br />
** This cannot be done int ITK 3.x because of backward compatibility issues<br />
* Make the semantics of the ITK containers match th one from STL<br />
** See this [http://www.itk.org/Bug/view.php?id=2893 bug report]<br />
* Set the default options values to provide the highest result quality<br />
** Some filters have default options values to produce quick transforms rather than high quality transforms. This is the case for the distance map filters, which produced squared results and don't use image spacing by default. This behavior is desirable in some conditions, but shouldn't be the default one.<br />
* Supported compilers<br />
** We should reconsider the list of supported compilers. ITK 4.0 might be a good time to drop, for example, MSVC 6.0 that only implements a subset of modern C++.<br />
** I would even suggest to go so far as to pick a very small set of very recent compilers that already implement support for parts of the new, upcoming C++0x standard. Especially, auto typeing, static_assert and maybe lambda expressions should be available for writing new code. <br />
* Define a transition period during which developments need not be backward compatible<br />
** Such a period could be defined in terms of a number of "beta" releases<br />
<br />
== Image Registration ==<br />
* Set up the infrastructure to ease the implementation of modern optimization schemes for image registration<br />
** Requires Hessian or pseudo-Hessians of the cost function<br />
** Requires several types of update rules (additive, compositional, inverse compositional, etc.)<br />
** References: "Lucas-Kanade 20 years on" by Baker et al.; "Homography-based 2D Visual Tracking and Servoing" by Benhimane and Malis, "Groupwise Geometric and Photometric Direct Image Registration" by Bartoli; etc.<br />
* Allow the use of regularization terms that depends on the spatial transformation. See [http://elastix.isi.uu.nl/doxygen/a00010.html elastix] for an example implementation.<br />
* Clean up the use of parameter scaling in the optimizers<br />
** One possibility would be that the optimizers only perform unscaled minimization. It would then be up to a cost function wrapper to do the rescaling and potentially return the opposite of the cost function. This is similar to how vnl optimizers are used in ITK<br />
** See also [http://elastix.isi.uu.nl/doxygen/a00193.html elastix] for another example implementation.<br />
* Optimizers should return the best visited value<br />
** See [http://public.kitware.com/Bug/bug_view_page.php?bug_id=3205 Bug 3205]<br />
* Modify transforms to support a consistent API across transform types<br />
* Modify order of parameters to be consistent across transforms.<br />
* Modify the base class for optimizers to support key optimizer API calls such as SetMaximize and SetNumberOfIterations or SetMaximumIteration<br />
* Make the registration framework work with vector images natively.<br />
** Currently several itk filters/functions assume that the pixel is of scalar type. This prevents from using the registration framework with vector images.<br />
** Several filters/functions useful for registration are specialized for vectors whereas it is often unnecessary. It is often quite easy to adapt the filters that assume scalar pixels to make them work with vector pixels. For example, there is a [http://www.itk.org/Doxygen/html/classitk_1_1VectorInterpolateImageFunction.html VectorInterpolateImageFunction], but the regular [http://www.itk.org/Doxygen/html/classitk_1_1InterpolateImageFunction.html InterpolateImageFunction] should do just fine. Actually, there is even a [http://www.itk.org/cgi-bin/viewcvs.cgi/Testing/Code/Common/itkLinearInterpolateImageFunctionTest.cxx?root=Insight&sortby=date&view=markup unit test] to check that the [http://www.itk.org/Doxygen/html/classitk_1_1LinearInterpolateImageFunction.html LinearInterpolateImageFunction] correctly handles vector images. Below is a list of filters that could potentially be removed:<br />
*** [http://www.itk.org/Doxygen/html/classitk_1_1VectorCastImageFilter.html VectorCastImageFilter]: could be reworked if we provide a conversion operator in the vector pixel class<br />
*** [http://www.itk.org/Doxygen/html/classitk_1_1VectorCentralDifferenceImageFunction.html VectorCentralDifferenceImageFunction]<br />
*** [http://www.itk.org/Doxygen/html/classitk_1_1VectorExpandImageFilter.html VectorExpandImageFilter]<br />
*** [http://www.itk.org/Doxygen/html/classitk_1_1VectorImageNeighborhoodAccessorFunctor.html VectorImageNeighborhoodAccessorFunctor]<br />
*** [http://www.itk.org/Doxygen/html/classitk_1_1VectorInterpolateImageFunction.html VectorInterpolateImageFunction]<br />
*** [http://www.itk.org/Doxygen/html/classitk_1_1VectorResampleImageFilter.html VectorResampleImageFilter]<br />
*** [http://www.itk.org/Doxygen/html/classitk_1_1VectorRescaleIntensityImageFilter.html VectorRescaleIntensityImageFilter]<br />
*** [http://www.itk.org/Doxygen/html/classitk_1_1VectorRescaleIntensityImageFilter.html VectorRescaleIntensityImageFilter]<br />
*** [http://www.itk.org/Doxygen/html/classitk_1_1VectorNeighborhoodInnerProduct.html VectorNeighborhoodInnerProduct]<br />
*** [http://www.itk.org/Doxygen/html/classitk_1_1VectorNearestNeighborInterpolateImageFunction.html VectorNearestNeighborInterpolateImageFunction]<br />
*** etc.<br />
** In cases where the implementation has to be slightly different for vector pixels, we should consider using partial template specialization.<br />
***This would require dropping support for visual c++ 6.<br />
** An initial simple implementation of vector image registration can be found on the [http://www.na-mic.org/svn/NAMICSandBox/trunk/VectorImageRegistrationMethod/ NAMIC SandBox].<br />
** Refactor the SymmetricSecondRankTensor to make possible to use it as pixel type for any filter that can process an image of multiple components.<br />
*** This requires to make "Dimension" equal to the current "InternalDimension".<br />
<br />
== Composite Transform ==<br />
* Define a composite transform which can contain any number of transforms, composed.<br />
* Only expose the parameters of the last transform for optimization (default)<br />
* Used in multivariate atlas formation (DTI reg with T1 reg with atlas)<br />
* Remove all of the Centered transforms<br />
* See Insight Journal Papers:<br />
** http://www.insight-journal.org/browse/publication/143<br />
** http://www.insight-journal.org/browse/publication/91<br />
<br />
== Architecture and Software engineering ==<br />
* Implement a pure virtual base class for each API to support instantiation of templated filters at run-time with different dimensions. Many classes in ITK are templated, for example over spatial dimension and pixel type, or over images that are templated over spatial dimension and pixel type. However, many of the operations that are carried out do not depend on the spatial dimension and pixel type. A pure virtual base class for a particular filter, such as itk::ResampleImageFilter, would define the API of the ResampleImageFilter without implementing any of the functions that depend on TInputImage, TOutputImage or TInterpolatorPrecisionType. This would enable a pointer to the virtual base class to be manipulated in code, and a specialized implementation with a particular TInputImage, TOutputImage and TInterpolatePrecisionType to be instantiated at run time. This would enable an image to be read in, its dimension and pixel type to be established at run time, an appropriate specialized class to be instantiated and used, rather than the current practice of fixing at compile time the dimension and pixel type that will be utilized. For example, a single program could be written using the virtual base class API with run-time instantiation of a 2D filter for floating point pixels if the input is a 2D with floating point pixels, and a 3D filter with unsigned short pixels if the input is 3D with unsigned short pixels.<br />
<br />
''Can you explain a bit more?''<br />
<br />
* Add interfaces to the algorithms that turn incomplete initialization into compile time error for "linear" environments or enable some kind of validation instead of throwing an exception in "dynamic" environments. In both cases, the entry points to doing real work of the algorithm should then be guarded by assertions regarding the required parameters, not exceptions - since ending up there without proper initialization would always be a programming error. <br />
** As a "linear" environments I define an implementations where the parameters and the input to an algorithm are completely determined by the program. In this case, an error in initialization (by missing a SetXXX method) usually is a programming error. Adding an initialization method or constructor that takes all required parameters would enable the developer to move this error from run-time to compile-time.<br />
** As a "dynamic" environments I imagine e.g. a GUI program, where the user can set the parameters to an algorithm dynamically. Here, a missing SetXXX is not a programming error, but a user error. However, since more than one parameter might be missing, exceptions are not a good way to report the problem. Instead, it should be possible to call some validation function that reports all the missing parameters to the user.<br />
<br />
* Allow partial template specialization, (which would imply [[Proposals:Dropping_Support_for_Visual_Studio_6.0 |dropping support for VC 6.0]]).<br />
<br />
* Discuss whether to move to TR1. Portability might be achieved through the [http://www.boost.org/doc/libs/1_39_0/doc/html/boost_tr1.html boost TR1 wrapper library].<br />
<br />
* SmartPointer< T > should be implicitly convertible to SmartPointer< U > whenever T* can be implicitly converted to U*.<br />
** This might be achieved by using TR1 smart pointers instead of the ITK 3.0 smart pointer implementation. It might however then be more complex to use the default factory mechanism as with [http://www.itk.org/cgi-bin/viewcvs.cgi/Testing/Code/Common/itkFactoryTestLib.cxx?root=Insight&view=markup itkFactoryTestLib.cxx] and [http://www.itk.org/cgi-bin/viewcvs.cgi/Testing/Code/Common/itkObjectFactoryTest2.cxx?root=Insight&view=markup itkObjectFactoryTest2].<br />
<br />
* Testing framework<br />
** Add a decent testing framework e.g. based on BOOST.test or googletest; see [http://www.itk.org/mailman/private/insight-developers/2008-December/011421.html discussion on the itk-developers]<br />
** [[ITK Release 4.0/Testing Framework]]<br />
<br />
* Code Revision Control<br />
** Migrate to Subversion or GIT <br />
<br />
* Portability issues<br />
** Discuss the use of fixed-width types to enhance portability and interoperability. This can be done by using [http://www.boost.org/doc/libs/1_39_0/boost/cstdint.hpp cstdint from boost].<br />
** Avoid the use of tryrun in the cmakelist and rely only on trycompile to ease cross-compilation<br />
<br />
== Internationalization ==<br />
* Allow the use of unicode file names, see this [http://public.kitware.com/Bug/view.php?id=9623 bug report]<br />
<br />
== Proper resampling/consistency in IndexToPhysicalPoint, ContinuousIndexToPhysicalPoint, Point* ==<br />
* Refactor all the interpolators<br />
** See [[Proposals:Refactoring Index Point Coordinate System]]<br />
** See [http://www.itk.org/Bug/view.php?id=6558 ITK Bug 6558]<br />
** Fix bug 0005335 - transform initializer computes geometric center incorrectly<br />
<br />
== Deformable Organisms ==<br />
<br />
* Move the framework from the IJ paper:<br />
** http://www.insight-journal.org/browse/publication/116<br />
** http://hdl.handle.net/1926/228<br />
<br />
== Make as much filters as possible able to run in place ==<br />
In place computation is a great way to avoid running out of memory when updating a pipeline. We should review all the existing filters to find the filters which could be implemented that way, and use InPlaceImageFilter has their base class.<br />
Also, a global setting to control the default in place/not in place behavior would be great.<br />
<br />
== Make the boundary conditions usage consistent across the toolkit ==<br />
At the moment, some filters let the user provide a boundary condition, some don't but use one internally, and some just don't use them at all. This should be consistent in the toolkit, and if it make sense, it should be changeable by the user.<br />
Boundary conditions also make some filters hard to enhance with much more efficient algorithms - see BoxMeanImageFilter for an example.<br />
<br />
== Replace the current implementation of Marching Cubes and add a 4D version ==<br />
<br />
The itkBinaryMask3DMeshSource filter currently provides the closest functionality to the Marching Cubes algorithm in ITK. However the code of this filter has to be rewritten in order to match the quality standards of the rest of the toolkit. As part of this rewrite we should provide implementations for 2D (marching squares), 3D marching cubes and a 4D version that could be used for segmenting 3D+time datasets.<br />
* See http://svn.na-mic.org/NAMICSandBox/trunk/MarchingHypercubes/<br />
<br />
== Normalize the Binary/Label/Grayscale usage in code and in the class names ==<br />
[[Proposals:Consistent_usage_of_label_and_binary_images]]<br />
<br />
== Use an image template parameter in the complex related filters ==<br />
<br />
== Arbitrary precision type ==<br />
<br />
for reconstruction and geometry processing, you might want to use arbitrary precision type. Boost has one, GMP is now LGPL.<br />
That also could be a feature of the numerical library, and then the solvers could directly use this, if needed.<br />
<br />
inspired from exct and filtered kernels in CGAL<br />
<br />
== Exact geometrical test (point in circle => delaunay ==<br />
<br />
If we cannot go for arbitrary precision types, in some case it is sufficient to support some operations to have exact geometrical predicates. This is mandatory for a robust delaunay implementation. The implementation for the point-in-circle predicate which is necessary and sufficient for exact 2D delaunay, is public domain.<br />
<br />
Note that abitrary precision would allow for any exact geometrical predicates.<br />
<br />
== 3rd Party Libraries ==<br />
<br />
* Out dated libraries<br />
** Many 3rd party libraries (ex libTIFF) are years out of date. One possibility is to update them to their newest official release. Another is to remove them and require developers to use their own version (i.e. USE_SYSTEM_TIFF).<br />
* Linear algebra package<br />
** The current linear algebra package used by ITK is VNL. It's performance and robustness is not very good, it is not actively maintained and cannot use a vendor back-end such as MKL. We should therefore discuss the alternative possibilities. Below is a list of potential linear algebra libraries:<br />
** Boost [http://www.boost.org/doc/libs/release/libs/numeric uBLAS] with [http://mathema.tician.de/node/391 bindings] for LAPACK<br />
*** [https://svn.boost.org/svn/boost/sandbox/numeric_bindings/ Trunk version of the automatically generated boost bindings]<br />
*** [http://mathema.tician.de/software/boost-bindings Packaged version of the old hand-written version of boost bindings]<br />
*** Aside from bindings, uBLAS could also rely on [http://devernay.free.fr/hacks/ublasJama.html ublasJama] for linear algebra<br />
** [http://www.mcs.anl.gov/petsc/petsc-as/ PETSc]<br />
** [http://home.gna.org/getfem/gmm_intro.html GMM++]<br />
** [http://www.cs.uiowa.edu/~dstewart/meschach/ Meschach]<br />
** [http://www.osl.iu.edu/research/mtl/ MTL] or [http://www.osl.iu.edu/research/mtl/mtl4/ MTL4]<br />
** [http://eigen.tuxfamily.org Eigen] seems nice. It has quite a few linear algebra operations embedded and seems [http://eigen.tuxfamily.org/index.php?title=Benchmark very fast].<br />
** Unify with the underlying routines of Numpy/Scipy [http://www.scipy.org]<br />
*** Some uBLAS/numpy bindings are available from [http://mathema.tician.de/software/pyublas pyUlas].<br />
** See also the [http://www.itk.org/Wiki/Proposals:Sparse_Linear_Solvers sparse linear solvers discussion page]<br />
* A fairly complete list of potential libraries can be found at [http://verdandi.gforge.inria.fr/doc/linear_algebra_libraries.pdf]<br />
* Numerical analysis package<br />
** The current numerical analysis package used by ITK is VNL. It's performance and robustness is not very good, it is not actively maintained. We should therefore discuss the alternative possibilities. Below is a list of potential alternatives:<br />
** The main numerical analysis tools we use from vnl are the optimizers. Most of these optimizers have an alternative quasi-ITK implementation in [http://elastix.isi.uu.nl/doxygen/a00448.html elastix].<br />
<br />
== Coding Style ==<br />
<br />
* The current descriptive naming scheme is certainly good to get a grip on the functionality, but the length of the names are, IMHO getting a bit out of hand. I would suggest to group similar classes into namespaces, like e.g. MeanSquaresImageToImageMetric and MatchCardinalityImageToImageMetric, and the likes into ImageToImageMetric and use the specific part as new class name (MeanSquares, MatchCardinality). For those preferring the long version ImageToImageMetric::MeanSquares is at least as descriptive, and others could use the using directive in their code. These namespaces would also help with the automatically generated documentation since classes would be better grouped by having namespace related pages instead of only the flat alphabetical ordering that currently exists. For backward compatibility, one could provide defines that should, of course, be only enabled as deprecated feature.<br />
<br />
* Currenty, all include files are included using only the file name and adding all the sub-directories of the ITK include tree to the search path. This adds quite some overhead to the compile time, since all these directories have to be searched. As an alternative I'd suggest to include the files like <BasickFilter/itkSomeFilter.h> or even change naming to <itk/BasickFilter/SomeFilter.h> and only add the itk include base path to the search path. As a result ...<br />
** the preprocessor only needs to find the subdirectory and then the file therein, <br />
** and in addition, if someone wants to look up something in the source code without firing up an IDE that automatically does the file lookup, it is easier to locate the include file based on this additional path information. <br />
**To make transition easier, one could define an extra CMAKE variable that would add the old include path for a backward compatible compile and in case of the second include style, let the old itkSomeFilter.h file emit a backward compatibility warning - just like g++ has warnings about e.g. including an old style <iostream.h> instead of the new <iostream>.<br />
<br />
== Wavelets Framework ==<br />
* Wavelets are intensively used in operations such as denoising and compressing. A common framework to decompose N-dimensionnal images with wavelets would be valuable. Such a framework could include :<br />
** a common way of representing wavelets,<br />
** a common way of representing multiscale images.<br />
* See the following Insight Journal papers:<br />
** [http://www.insight-journal.org/browse/publication/103 The Generalised Image Fusion Toolkit (GIFT)]<br />
** [http://www.insight-journal.org/browse/publication/155 Spherical Wavelet ITK Filter]<br />
<br />
== Label map writer ==<br />
* A class has been created to store labelmaps in memory, considering a writer/reader couple to store this information may be valuable.<br />
<br />
== DICOM ==<br />
<br />
Writing DICOM files should be much easier. Two modes should be available:<br />
<br />
# For basic user the DICOM image writer should write out simple DICOM file (Secondary Capture IOD's objects). This makes thoses DICOM file the exact equivalent of PNG or TIFF representation.<br />
# For advanced users: There should be a way for passing information from -say- the input DICOM files to the output DICOM files. Filters should be added to manipulate those meta data. Typical examples includes:<br />
#* a derivation filter which add "DERIVED" and setup the Derivation Description, Source Image Sequence & Derivation Code Sequence<br />
#* a lossy generator that mark that image was degraded for professional interpretation and thus tags should be updated (Lossy Image Compression & Lossy Image Compression Ratio)<br />
#* changing of SOP Class should be allowed, for instance input is CT Image, but Segmentation Storage is needed for output (Registration Storage...)<br />
<br />
For the advanced user, it will be possible to write out other class than just the Secondary Capture one, since there will be a way to specify which SOP Class to use for the output DICOM files.<br />
<br />
== Support clang compiler ==<br />
* I'd like to be able to build ITK using the clang compiler (http://clang.llvm.org/)<br />
* CMake and GDCM can be built with clang, but ITK currently cannot.<br />
* clang itself can be built with CMake.<br />
* I have already created a dashboard http://www.cdash.org/CDash/buildSummary.php?buildid=662643</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Migration_Plan&diff=24989ITK/Release 4/Migration Plan2010-07-12T14:20:13Z<p>Seanmcbride: /* Revision Control */</p>
<hr />
<div>'''Migration Plan'''<br />
<br />
The Migration Plan covers two main topics<br />
<br />
* Infrastructure Tools<br />
* Facilitating migration to users<br />
<br />
The following two documents are the (draft) of the proposed migration plan. They are open for discussion.<br />
<br />
= Infrastructure Tools =<br />
<br />
== Revision Control ==<br />
<br />
* Revision control : Git + gitorious<br />
* Git Sandbox in Github: [http://github.com/InsightSoftwareConsortium/Insight Insight]<br />
** Learn Git<br />
*** [http://git-scm.com/documentation Git Documentation]<br />
**** [http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html Git Tutorial]<br />
**** [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Every Day Git]<br />
**** Videos<br />
***** [http://www.youtube.com/watch?v=4XpnKHJAok8 Linus Tolvas on Git]<br />
***** [http://www.youtube.com/watch?v=8dhZ9BXQgc4 Randal Schwartz on Git]<br />
***** [http://excess.org/article/2008/07/ogre-git-tutorial/ Git Tutorial Talk]<br />
***** [http://gitcasts.com/ Git Topics]<br />
** Join us and make your newbie mistake in the Git Sandbox<br />
<br />
== Code Review ==<br />
<br />
* Code review : [http://code.google.com/p/gerrit/ Gerrit]<br />
** This is the code review tool used by: [https://review.source.android.com/ Google Android]<br />
** See Gerrit used in [http://gold.cryos.net:8080/#project,open,avogadro,n,z Avogadro]<br />
<br />
== Testing ==<br />
<br />
* Testing framework<br />
** [http://code.google.com/p/googletest/ Google Testing] +<br />
** CTest +<br />
** Custom ITK classes<br />
** See Status in the [http://github.com/InsightSoftwareConsortium/Insight Insight Sandbox] in Github:<br />
*** [http://github.com/InsightSoftwareConsortium/Insight/tree/master/Testing/Unit/GoogleTest/ GoogleTest in Insight]<br />
<br />
= Users Migration =<br />
<br />
[[image:ITKv4-TransitionPlanProposal.png|529px]]<br />
<br />
<br />
* [[media:ITKv4-TransitionPlanProposal.pdf|Transition Plan - Presentation - PDF]]<br />
* [[media:ITKv4-TransitionPlan-Draft.pdf|Transition Plan - Details - PDF]]</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=ITK/Second_Life&diff=17432ITK/Second Life2009-11-13T18:41:36Z<p>Seanmcbride: spelling</p>
<hr />
<div>__TOC__<br />
<br />
<br />
= Rationale =<br />
<br />
Given the growth and internationalization of the ITK development team we are experimenting with other mechanisms of communication and coordination.<br />
<br />
<br />
We are therefore experimenting with new technologies hoping to find a new method of communication that can effectively include developers from different geographical zones.<br />
<br />
<br />
The Virtual World of Second Life <br />
<br />
http://www.secondlife.com/<br />
<br />
provides a very rich environment of communication<br />
<br />
= ITK TCON =<br />
<br />
<br />
In a first experiment, we will hold the ITK Tcon of<br />
<br />
Friday August 22nd, 2008<br />
1:00pm - 2:00pm<br />
EST (New York Time)<br />
<br />
In the virtual World of<br />
<br />
"Second Life"<br />
http://secondlife.com/<br />
<br />
<br />
== Location ==<br />
<br />
The location for the meeting will be the<br />
<br />
"Linden Open Source Project HQ"<br />
<br />
You can *teleport* to this location by clicking on the following link:<br />
<br />
http://slurl.com/secondlife/Hippotropolis/238/14/24/?img=http%3A//public.kitware.com/Insight/Doxygen/html/itkLogo.jpg&title=ITK%20Tcon&msg=Insight%20Toolkit%20%28ITK%29%20Tcon<br />
<br />
[[image:SecondLife-ITKTcon-01_001.jpg]]<br />
<br />
= What is Second Life =<br />
<br />
Second Life is a virtual environment that is currently used by many<br />
academic institutions including:<br />
<br />
* MIT<br />
* Princeton<br />
* Harvard<br />
* Stanford<br />
* Duke University<br />
* UNC-Chapel Hill<br />
* University of Illinois at Urbana-Champaign.<br />
<br />
<br />
For a full list, please see following link:<br />
<br />
http://www.simteach.com/wiki/index.php?title=Institutions_and_Organizations_in_SL#UNIVERSITIES.2C_COLLEGES_.26_SCHOOLS<br />
<br />
= How to Prepare =<br />
<br />
<br />
In order to visit Second Life, you must install a the Second Life Client<br />
in your computer. The Client is Open Source software, distributed under<br />
a GPL License, [ and it is configured with CMake :-) ]<br />
<br />
<br />
You can download binaries for Windows, Linux and Mac from:<br />
<br />
* http://secondlife.com/support/downloads.php<br />
<br />
<br />
Then, you must create an account (it is free of charge), at:<br />
<br />
* https://secure-web23.secondlife.com/join/index.php<br />
<br />
<br />
If you already have a Second Life account for you personal purposes,<br />
you may want to consider creating a second account, so you can customize<br />
it better for participating in a professional setting.<br />
<br />
<br />
# Skip the step of joining a community<br />
# Select an Avatar<br />
# Select a First Name (these names are fictitious, please feel free to express yourself, but be sensitive to what other cultures may consider offensive).<br />
# Your Second Life Last name will be selected from a limited list. Again, it is up to your preferences.<br />
<br />
<br />
Once you have a First Name, Last Name and Password, you will be<br />
able to launch the client and to log in. After logging in, you can<br />
click on the SLURL (Second Life URL) listed above, to teleport to<br />
the "Linden Open Source Project HQ".<br />
<br />
Once inside Second Life you will have the opportunity to customize<br />
the appearance of your Avatar.<br />
<br />
<br />
You will need speakers (or headphones) and a microphone to be able<br />
to participate in the discussions of the Tcon. There is also a text<br />
messaging capability that we can use for coordination, but we mostly<br />
anticipate to be using voice communication.<br />
<br />
= Who Is Who ? =<br />
<br />
Since Avatar names inside SecondLife are fictitious, we are adding here a table that matches Real-Life names to Second-Life names. <br />
<br />
Please note the SecondLife privacy rule prevent you/us from disclosing real names of any Avatar. Therefore, it is '''only''' up to every participant to decide if they want to publicly disclose their real names in this table. Please add to this table '''only''' your real-name, do not disclose anybody's real name.<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Real Life Name !! Second Life Name <br />
|-<br />
| Luis Ibanez (Kitware) || Void Svoboda<br />
|-<br />
| Dan White MPI-CBG Dresden || Chalkie666 Nowhere<br />
|-<br />
| Sebastien Barre (Kitware) || DarthCorleone Naidoo<br />
|-<br />
| Dan Mueller (Philips) || Daneel Osterham<br />
|-<br />
| Gaëtan Lehmann (INRA) || Gaetan Exonar<br />
|-<br />
| Alex. Gouaillard (Harvard) || agouaillard Bellic<br />
|-<br />
| Bradley Lowekamp (LMC NLM) || Bradley24 Morpork<br />
|-<br />
| Kent Williams (Univ. Iowa) || Kent Wirefly<br />
|-<br />
| Wesley Turner (Kitware) || Wesley Gravois<br />
|-<br />
| Kishore Mosaliganti (Harvard) || Kishore Craziboi<br />
|-<br />
| Arnaud Gelas (Harvard) || Arnaud Cluny<br />
|-<br />
| Next Real Life Name || Next Second Life Name<br />
|}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4_Planning&diff=15932ITK/Release 4 Planning2009-07-08T22:50:56Z<p>Seanmcbride: </p>
<hr />
<div>= Wish List =<br />
<br />
== Oriented Images ==<br />
* Support ND image in N+1 dimension<br />
** 2D image can have an origin specified in 3D, thus a series of 2D images is not always Z-aligned<br />
* All images are oriented - remove concept of an un-oriented image<br />
* Check use of orientation throughout ITK<br />
* Support re-orientation of ND oriented images<br />
** Using anything other than 3D images won't compile with itkOrientedImageFilter<br />
<br />
** Spatial Objects<br />
** Meshes<br />
* Suggestions<br />
** [[ITK_Release_4.0_Orientation_by_Kent]]<br />
** [[ITK_Release_4.0_Orientation_by_Torsten]]<br />
** [[ITK_Release_4.0_Orientation_by_Michael]]<br />
<br />
== Image Representation ==<br />
* Allow the use of strides that are not equal to the image width<br />
** Would ease the collaboration of ITK with opencv<br />
** Would allow the use of sse operations<br />
** Might be considered redundant with correct use of image regions but is not since GetLargestPossibleRegion should correspond to the image width and not its stride<br />
* Drop the itk::Image::GetBufferPointer() method<br />
** This method has been many time described as a problem to implement new image layouts.<br />
** As expressed above, we need however to be able to use the memory held by ITK images within other libraries. This could potentially be done by making itk::Image be only a base class that has no knowledge of the memory layout and by implementing different image subclasses.<br />
* Consider replacing ImportImageContainer by std::vector or using std::vector to implement it<br />
** This would give STL iterators that operate on the whole image literally for free and make it easy to use a lot of algorithms implemented in STL and BOOST<br />
<br />
== Statistics ==<br />
* Complete statistics refactoring (see NAMIC sandbox)<br />
<br />
== FEM Meshes ==<br />
* Consolidate FEM Meshes and ITK Meshes<br />
<br />
== Backward compatibility and cleanup ==<br />
* Clean-up CMake Vars ==<br />
** See proposal [[ITK_CMake_Style|HERE]].<br />
* Remove Deprecated Features<br />
** Functions that have been deprecated (and appropriately marked as such) for more than 3 releases should be removed.<br />
* Set the default options values to provide the highest result quality<br />
** Some filters have default options values to produce quick transforms rather than high quality transforms. This is the case for the distance map filters, which produced squared results and don't use image spacing by default. This behavior is desirable in some conditions, but shouldn't be the default one.<br />
* Supported compilers<br />
** We should reconsider the list of supported compilers. ITK 4.0 might be a good time to drop, for example, MSVC 6.0 that only implements a subset of modern C++.<br />
* Define a transition period during which developments need not be backward compatible<br />
** Such a period could be defined in terms of a number of "beta" releases<br />
<br />
== Image Registration ==<br />
* Set up the infrastructure to ease the implementation of modern optimization schemes for image registration<br />
** Requires Hessian or pseudo-Hessians of the cost function<br />
** Requires several types of update rules (additive, compositional, inverse compositional, etc.)<br />
** References: "Lucas-Kanade 20 years on" by Baker et al.; "Homography-based 2D Visual Tracking and Servoing" by Benhimane and Malis, "Groupwise Geometric and Photometric Direct Image Registration" by Bartoli; etc.<br />
* Clean up the use of parameter scaling in the optimizers<br />
** One possibility would be that the optimizers only perform unscaled minimization. It would then be up to a cost function wrapper to do the rescaling and potentially return the opposite of the cost function. This is similar to how vnl optimizers are used in ITK<br />
* Optimizers should return the best visited value<br />
** See [http://public.kitware.com/Bug/bug_view_page.php?bug_id=3205 Bug 3205]<br />
* Modify transforms to support a consistent API across transform types<br />
* Modify order of parameters to be consistent across transforms.<br />
* Modify the base class for optimizers to support key optimizer API calls such as SetMaximize and SetNumberOfIterations or SetMaximumIteration<br />
<br />
== Composite Transform ==<br />
* Define a composite transform which can contain any number of transforms, composed.<br />
* Only expose the parameters of the last transform for optimization (default)<br />
* Used in multivariate atlas formation (DTI reg with T1 reg with atlas)<br />
* Remove all of the Centered transforms<br />
* See Insight Journal Papers:<br />
** http://www.insight-journal.org/browse/publication/143<br />
** http://www.insight-journal.org/browse/publication/91<br />
<br />
== Architecture ==<br />
* Implement a pure virtual base class for each API to support instantiation of templated filters at run-time with different dimensions. <br />
<br />
''Can you explain a bit more?''<br />
<br />
* Add interfaces to the algorithms that turn incomplete initialization into compile time error for "linear" environments or enable some kind of validation instead of throwing an exception in "dynamic" environments. In both cases, the entry points to doing real work of the algorithm should then be guarded by assertions regarding the required parameters, not exceptions - since ending up there without proper initialization would always be a programming error. <br />
** As a "linear" environments I define an implementations where the parameters and the input to an algorithm are completely determined by the program. In this case, an error in initialization (by missing a SetXXX method) usually is a programming error. Adding an initialization method or constructor that takes all required parameters would enable the developer to move this error from run-time to compile-time.<br />
** As a "dynamic" environments I imagine e.g. a GUI program, where the user can set the parameters to an algorithm dynamically. Here, a missing SetXXX is not a programming error, but a user error. However, since more than one parameter might be missing, exceptions are not a good way to report the problem. Instead, it should be possible to call some validation function that reports all the missing parameters to the user.<br />
<br />
* Allow partial template specialization, (which would imply [[Proposals:Dropping_Support_for_Visual_Studio_6.0 |dropping support for VC 6.0]]).<br />
<br />
* Discuss whether to move to TR1. Portability might be achieved through the [http://www.boost.org/doc/libs/1_39_0/doc/html/boost_tr1.html boost TR1 wrapper library].<br />
<br />
* SmartPointer< T > should be implicitly convertible to SmartPointer< U > whenever T* can be implicitly converted to U*.<br />
** This might be achieved by using TR1 smart pointers instead of the ITK 3.0 smart pointer implementation. It might however then be more complex to use the default factory mechanism as with [http://www.itk.org/cgi-bin/viewcvs.cgi/Testing/Code/Common/itkFactoryTestLib.cxx?root=Insight&view=markup itkFactoryTestLib.cxx] and [http://www.itk.org/cgi-bin/viewcvs.cgi/Testing/Code/Common/itkObjectFactoryTest2.cxx?root=Insight&view=markup itkObjectFactoryTest2].<br />
<br />
== Proper resampling/consistency in IndexToPhysicalPoint, ContinuousIndexToPhysicalPoint, Point* ==<br />
* Refactor all the interpolators<br />
** See [[Proposals:Refactoring Index Point Coordinate System]]<br />
** See [http://www.itk.org/Bug/view.php?id=6558 ITK Bug 6558]<br />
** Fix bug 0005335 - transform initializer computes geometric center incorrectly<br />
<br />
== Deformable Organisms ==<br />
<br />
* Move the framework from the IJ paper:<br />
** http://www.insight-journal.org/browse/publication/116<br />
** http://hdl.handle.net/1926/228<br />
<br />
== Make as much filters as possible able to run in place ==<br />
In place computation is a great way to avoid running out of memory when updating a pipeline. We should review all the existing filters to find the filters which could be implemented that way, and use InPlaceImageFilter has their base class.<br />
Also, a global setting to control the default in place/not in place behavior would be great.<br />
<br />
== Make the boundary conditions usage consistent across the toolkit ==<br />
At the moment, some filters let the user provide a boundary condition, some don't but use one internally, and some just don't use them at all. This should be consistent in the toolkit, and if it make sense, it should be changeable by the user.<br />
Boundary conditions also make some filters hard to enhance with much more efficient algorithms - see BoxMeanImageFilter for an example.<br />
<br />
== Replace the current implementation of Marching Cubes and add a 4D version ==<br />
<br />
The itkBinaryMask3DMeshSource filter currently provides the closest functionality to the Marching Cubes algorithm in ITK. However the code of this filter has to be rewritten in order to match the quality standards of the rest of the toolkit. As part of this rewrite we should provide implementations for 2D (marching squares), 3D marching cubes and a 4D version that could be used for segmenting 3D+time datasets.<br />
<br />
== Normalize the Binary/Label/Grayscale usage in code and in the class names ==<br />
[[Proposals:Consistent_usage_of_label_and_binary_images]]<br />
<br />
== Use an image template parameter in the complex related filters ==<br />
<br />
== Testing framework == <br />
Add a decent testing framework e.g. based on BOOST.test or googletest; see [http://www.itk.org/mailman/private/insight-developers/2008-December/011421.html discussion on the itk-developers]<br />
<br />
== Code Revision Control ==<br />
<br />
* Migrate to Subversion<br />
<br />
== Arbitrary precision type ==<br />
<br />
for reconstruction and geometry processing, you might want to use arbitrary precision type. Boost has one, GMP is now LGPL.<br />
That also could be a feature of the numerical library, and then the solvers could directly use this, if needed.<br />
<br />
inspired from exct and filtered kernels in CGAL<br />
<br />
== Exact geometrical test (point in circle => delaunay ==<br />
<br />
If we cannot go for arbitrary precision types, in some case it is sufficient to support some operations to have exact geometrical predicates. This is mandatory for a robust delaunay implementation. The implementation for the point-in-circle predicate which is necessary and sufficient for exact 2D delaunay, is public domain.<br />
<br />
Note that abitrary precision would allow for any exact geometrical predicates.<br />
<br />
== Update 3rd Party Libraries ==<br />
<br />
Many 3rd party libraries (ex libTIFF) are years out of date. One possibility is to update them to their newest official release. Another is to remove them and require developers to use their own version (i.e. USE_SYSTEM_TIFF).</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK_5.4_Release_Planning&diff=14493VTK 5.4 Release Planning2009-01-19T20:59:55Z<p>Seanmcbride: /* What's New in VTK 5.4? */</p>
<hr />
<div>== Planned Schedule ==<br />
<br />
* Preparation email: January 19, 2008<br />
** [http://www.vtk.org/pipermail/vtk-developers/2009-January/005752.html On the developers' mailing list]<br />
* Create VTK-5-4 branch: beginning of February, 2009<br />
* Release VTK 5.4.0: as soon after branching as practical according to the dashboards<br />
<br />
== What's New in VTK 5.4? ==<br />
<br />
New features in VTK since the 5.2 release include:<br />
* Geovis kit<br />
* Updated Utilities: freetype (now at 2.3.7)<br />
* More than [[New54Classes|XX new C++ classes]].<br />
* More than [[New54Classes#New_Tests_in_this_Release|YY new C++ tests]] running on most dashboards<br />
<br />
== API Changes ==<br />
<br />
No known significant API changes compared to 5.2<br />
<br />
== OpenGL requirements ==<br />
<br />
Same as VTK 5.2:<br />
[[VTK FAQ#VTK_5.2|See this section in the Frequently asked questions (FAQ)]]</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=ITK_Third_Party_Library_Patrol&diff=13661ITK Third Party Library Patrol2008-10-01T14:54:09Z<p>Seanmcbride: </p>
<hr />
<div>'''Third-Party Library Patrol'''<br />
<br />
= About =<br />
<br />
The Third-Party Library Patrol is a group of developers who commit to regularly update the versions of third party libraries that are carried along with ITK in the Utilities directory.<br />
<br />
The ideal schedule of updates is to bring the third-party libraries to their most-recent version, before every quarterly release of ITK.<br />
<br />
= Shared Code =<br />
<br />
Note that ITK and VTK both use many of the same 3rd party libraries. However, each has its own separate copy in source control. When updating a library, check if the library is used by both ITK and VTK, ideally, both should be updated together and kept in sync.<br />
<br />
= Members =<br />
<br />
The following sections list the members of the patrol for each one of the Third Party Libraries distributed with ITK. Most of these libraries are hosted in the Insight/Utilities directory.<br />
<br />
== Expat ==<br />
<br />
== GDCM ==<br />
*Mathieu Malaterre<br />
<br />
== JPEG ==<br />
*Mathieu Malaterre<br />
<br />
== JPEG 2000 ==<br />
*Mathieu Malaterre<br />
<br />
== MetaImage ==<br />
<br />
* Stephen Aylward<br />
* Julien Jomier<br />
<br />
== Nifti ==<br />
<br />
== Nrrd ==<br />
<br />
== PNG ==<br />
<br />
== TIFF ==<br />
<br />
== VXL ==<br />
<br />
== ZLIB ==<br />
<br />
* Sean McBride</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/Third_Party_Library_Patrol&diff=13660VTK/Third Party Library Patrol2008-10-01T14:54:03Z<p>Seanmcbride: </p>
<hr />
<div>'''Third-Party Library Patrol'''<br />
<br />
= About =<br />
<br />
The Third-Party Library Patrol is a group of developers who commit to regularly update the versions of third party libraries that are carried along with VTK in the Utilities directory.<br />
<br />
The ideal schedule of updates is to bring the third-party libraries to their most-recent version, before every release of VTK.<br />
<br />
= Shared Code =<br />
<br />
Note that ITK and VTK both use many of the same 3rd party libraries. However, each has its own separate copy in source control. When updating a library, check if the library is used by both ITK and VTK, ideally, both should be updated together and kept in sync.<br />
<br />
= Members =<br />
<br />
The following sections list the members of the patrol for each one of the Third Party Libraries distributed with VTK. Most of these libraries are hosted in the VTK/Utilities directory.<br />
<br />
== exodus2 ==<br />
<br />
== expat ==<br />
<br />
== freetype ==<br />
<br />
* Sean McBride<br />
<br />
== jpeg ==<br />
<br />
== libxml2 ==<br />
<br />
<br />
== metaio ==<br />
<br />
<br />
== netcdf ==<br />
<br />
<br />
== png ==<br />
<br />
<br />
== sqlite ==<br />
<br />
== TIFF ==<br />
<br />
== ZLIB ==<br />
<br />
* Sean McBride</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/Third_Party_Library_Patrol&diff=13659VTK/Third Party Library Patrol2008-10-01T14:50:14Z<p>Seanmcbride: /* Members */</p>
<hr />
<div>'''Third-Party Library Patrol'''<br />
<br />
= About =<br />
<br />
The Third-Party Library Patrol is a group of developers who commit to regularly update the versions of third party libraries that are carried along with VTK in the Utilities directory.<br />
<br />
The ideal schedule of updates is to bring the third-party libraries to their most-recent version, before every release of VTK.<br />
<br />
= Members =<br />
<br />
The following sections list the members of the patrol for each one of the Third Party Libraries distributed with VTK. Most of these libraries are hosted in the VTK/Utilities directory.<br />
<br />
== exodus2 ==<br />
<br />
== expat ==<br />
<br />
== freetype ==<br />
<br />
* Sean McBride<br />
<br />
== jpeg ==<br />
<br />
== libxml2 ==<br />
<br />
<br />
== metaio ==<br />
<br />
<br />
== netcdf ==<br />
<br />
<br />
== png ==<br />
<br />
<br />
== sqlite ==<br />
<br />
== TIFF ==<br />
<br />
== ZLIB ==<br />
<br />
* Sean McBride</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/Third_Party_Library_Patrol&diff=13658VTK/Third Party Library Patrol2008-10-01T14:49:15Z<p>Seanmcbride: /* ZLIB */</p>
<hr />
<div>'''Third-Party Library Patrol'''<br />
<br />
= About =<br />
<br />
The Third-Party Library Patrol is a group of developers who commit to regularly update the versions of third party libraries that are carried along with VTK in the Utilities directory.<br />
<br />
The ideal schedule of updates is to bring the third-party libraries to their most-recent version, before every release of VTK.<br />
<br />
= Members =<br />
<br />
The following sections list the members of the patrol for each one of the Third Party Libraries distributed with VTK. Most of these libraries are hosted in the VTK/Utilities directory.<br />
<br />
== exodus2 ==<br />
<br />
== expat ==<br />
<br />
== freetype ==<br />
Sean McBride<br />
<br />
== jpeg ==<br />
<br />
== libxml2 ==<br />
<br />
<br />
== metaio ==<br />
<br />
<br />
== netcdf ==<br />
<br />
<br />
== png ==<br />
<br />
<br />
== sqlite ==<br />
<br />
== TIFF ==<br />
<br />
== ZLIB ==<br />
Sean McBride</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/Third_Party_Library_Patrol&diff=13657VTK/Third Party Library Patrol2008-10-01T14:49:02Z<p>Seanmcbride: /* freetype */</p>
<hr />
<div>'''Third-Party Library Patrol'''<br />
<br />
= About =<br />
<br />
The Third-Party Library Patrol is a group of developers who commit to regularly update the versions of third party libraries that are carried along with VTK in the Utilities directory.<br />
<br />
The ideal schedule of updates is to bring the third-party libraries to their most-recent version, before every release of VTK.<br />
<br />
= Members =<br />
<br />
The following sections list the members of the patrol for each one of the Third Party Libraries distributed with VTK. Most of these libraries are hosted in the VTK/Utilities directory.<br />
<br />
== exodus2 ==<br />
<br />
== expat ==<br />
<br />
== freetype ==<br />
Sean McBride<br />
<br />
== jpeg ==<br />
<br />
== libxml2 ==<br />
<br />
<br />
== metaio ==<br />
<br />
<br />
== netcdf ==<br />
<br />
<br />
== png ==<br />
<br />
<br />
== sqlite ==<br />
<br />
== TIFF ==<br />
<br />
== ZLIB ==</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=ITK_Roadmap_2008_2009&diff=13608ITK Roadmap 2008 20092008-09-23T14:31:21Z<p>Seanmcbride: /* Updating 3rd Party Libraries */</p>
<hr />
<div>= Introduction =<br />
<br />
The future developement of ITK relies heavily on feedback from the community of users and developers as well as guidelines from the clinical and medical research community.<br />
<br />
This page is intended to gather feedback regarding the future direction of ITK and in particular to list specific features and functionalities that would make the toolkit more useful for the medical imaging community.<br />
<br />
= Users/Developers Support =<br />
<br />
This section relates to the services that will help beginners to start with ITK as well as material that will help experienced users to take better advantage of the functionalities available in the Insight toolkit.<br />
<br />
* Tutorials<br />
* Mailing List Support<br />
* Bug Tracking / Triage / Fixing<br />
* Weekly conferences<br />
<br />
= Suggested Items =<br />
<br />
== Updating 3rd Party Libraries ==<br />
<br />
It will be desirable to update the versions of the current libraries. There are several reasons for this. First, many of the 3rd party libraries are often updated to fix security vulnerabilities; without these fixes applied, ITK is vulnerable to publicized bugs. Second, the newer versions of libraries have generally better support for 64 bit, which has only recently become mainstream.<br />
<br />
=== libTIFF ===<br />
<br />
* This is bug 5469.<br />
* Current version is vulnerable to published security vulnerabilities.<br />
* What version to use ? 3.8.2 is the latest stable version, and is the version used by VTK.<br />
* Volunteers ?<br />
* Compilers supported ?<br />
<br />
=== OpenJPEG ===<br />
<br />
=== GDCM ===<br />
<br />
=== VXL/VNL ===<br />
<br />
=== libPNG ===<br />
* This is bug 5470.<br />
* Current version is vulnerable to published security vulnerabilities.</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK_5.2_Release_Planning&diff=12968VTK 5.2 Release Planning2008-09-02T17:24:44Z<p>Seanmcbride: /* What's New in VTK 5.2? */</p>
<hr />
<div>== Planned Schedule ==<br />
<br />
* Announcement email: January 28, 2008<br />
** [http://public.kitware.com/pipermail/vtk-developers/2008-January/004939.html On the developers' mailing list]<br />
** [http://public.kitware.com/pipermail/vtkusers/2008-January/094114.html On the users' mailing list]<br />
* Create VTK-5-2 branch: end of April, 2008<br />
* Merge requested fixes from CVS HEAD<br />
* Release VTK 5.2.0: August 28, 2008<br />
** [http://www.vtk.org/pipermail/vtk-developers/2008-August/005505.html Developers' list]<br />
** [http://www.vtk.org/pipermail/vtkusers/2008-August/096694.html Users' list]<br />
<br />
== What's New in VTK 5.2? ==<br />
<br />
New features in VTK since the 5.0 release include:<br />
* Infovis kit<br />
* Views kit<br />
* New Widgets architecture and more than a dozen new widgets<br />
* New infrastructure for selection of arbitrary subsets<br />
* Substantially improved support for composite data objects<br />
* New Utilities: freerange, verdict, libxml2, metaio, sqlite<br />
* Updated Utilities: freetype, zlib, libtiff<br />
* More than [[New52Classes|300 new C++ classes]].<br />
* More than [[New52Classes#New_Tests_in_this_Release|100 new C++ tests]] running on most dashboards<br />
* Improvements to PLY file support<br />
* Many bug fixes, including much improved Java wrapping support<br />
* Mac OS X-specific fixes<br />
** Defaults to building using Cocoa instead of Carbon<br />
** Can now be compiled against the 10.5 SDK<br />
** Can now be built as a Universal Binary<br />
** Initial support for Resolution Independence in 10.5<br />
<br />
== API Changes ==<br />
<br />
[[VTK FAQ#API_Changes_in_VTK_5.2|See this section in the Frequently asked questions (FAQ)]]<br />
<br />
== OpenGL requirements ==<br />
<br />
[[VTK FAQ#VTK_5.2|See this section in the Frequently asked questions (FAQ)]]</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK_5.2_Release_Planning&diff=11491VTK 5.2 Release Planning2008-01-29T00:02:45Z<p>Seanmcbride: /* What's New in VTK 5.2? */</p>
<hr />
<div>== Planned Schedule ==<br />
<br />
* Announcement email: January 28, 2008<br />
** [http://public.kitware.com/pipermail/vtk-developers/2008-January/004939.html On the developers' mailing list]<br />
** [http://public.kitware.com/pipermail/vtkusers/2008-January/094114.html On the users' mailing list]<br />
* Create VTK-5-2 branch: end of February, 2008<br />
* Fix bugs in priority order: through the end of March, 2008<br />
* Stabilize the dashboards and release the first release candidate for VTK 5.2: early April, 2008<br />
<br />
== What's New in VTK 5.2? ==<br />
<br />
New features in VTK since the 5.0 release include:<br />
* Infovis kit<br />
* Views kit<br />
* New Widgets architecture and more than a dozen new widgets<br />
* New Utilities: freerange, verdict, libxml2, metaio, sqlite<br />
* Updated Utilities: freetype, zlib<br />
* More than 300 new C++ classes.<br />
* More than 100 new C++ tests running on most dashboards<br />
* Improvements to PLY file support<br />
* Many bug fixes, including much improved Java wrapping support<br />
* Mac OS X-specific fixes<br />
** Defaults to building using Cocoa instead of Carbon<br />
** Can now be compiled against the 10.5 SDK<br />
** Can now be built as a Universal Binary<br />
** Initial support for Resolution Independence in 10.5<br />
<br />
== API Changes ==<br />
<br />
[[VTK FAQ#API_Changes_in_VTK_5.2|See this section in the Frequently asked questions (FAQ)]]</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK_5.2_Release_Planning&diff=11490VTK 5.2 Release Planning2008-01-29T00:01:36Z<p>Seanmcbride: /* What's New in VTK 5.2? */</p>
<hr />
<div>== Planned Schedule ==<br />
<br />
* Announcement email: January 28, 2008<br />
** [http://public.kitware.com/pipermail/vtk-developers/2008-January/004939.html On the developers' mailing list]<br />
** [http://public.kitware.com/pipermail/vtkusers/2008-January/094114.html On the users' mailing list]<br />
* Create VTK-5-2 branch: end of February, 2008<br />
* Fix bugs in priority order: through the end of March, 2008<br />
* Stabilize the dashboards and release the first release candidate for VTK 5.2: early April, 2008<br />
<br />
== What's New in VTK 5.2? ==<br />
<br />
New features in VTK since the 5.0 release include:<br />
* Infovis kit<br />
* Views kit<br />
* New Widgets architecture and more than a dozen new widgets<br />
* New Utilities: freerange, verdict, libxml2, metaio, sqlite<br />
* Updated Utilities: freetype, zlib<br />
* More than 300 new C++ classes.<br />
* More than 100 new C++ tests running on most dashboards<br />
* Improvements to PLY file support<br />
* Many bug fixes, including much improved Java wrapping support<br />
* Mac OS X-specific fixes<br />
** Defaults to building using Cocoa instead of Carbon<br />
** Can now be compiled against the 10.5 SDK<br />
** Can now be built as a Universal Binary<br />
<br />
== API Changes ==<br />
<br />
[[VTK FAQ#API_Changes_in_VTK_5.2|See this section in the Frequently asked questions (FAQ)]]</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=11437VTK/FAQ2008-01-23T15:10:13Z<p>Seanmcbride: /* What is the release schedule for VTK */</p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk is 5.0.4 (released on 2008-01-22). This release is available at:<br />
<br />
http://www.vtk.org/files/release/5.0/<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly/<br />
<br />
See http://www.vtk.org/get-software.php for more information.<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesisitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Can I contribute money? ===<br />
<br />
Please don't send money. Not that we think you're going to send in<br />
unsolicited money. But if you were thinking about it, stop. It would<br />
just complicate our lives and make for all sorts of tax problems.<br />
<br />
(Note: if you are a company or funding institution, and would like to fund<br />
features or development, please contact Kitware http://www.kitware.com .)<br />
<br />
=== Is there a mailing list or Usenet newsgroup for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
There is also a newsgroup that mirrors the mailinglist. At this point it<br />
seems that mirror is down. Mail to the mailinglist used to be posted the<br />
newsgroup, but posts on the newsgroup were not sent to the mailinglist.<br />
The newsgroup was located at:<br />
news://scully.esat.kuleuven.ac.be/vtk.mailinglist<br />
<br />
http://www.gmane.org is a bidirectional mail-to-news gateway that carries the vtkusers mailing list. Its located here: news://news.gmane.org/gmane.comp.lib.vtk.user or here: http://news.gmane.org/gmane.comp.lib.vtk.user. vtkusers mails have been archived since April 2002 and they never expire. You can read and send mails to the vtkusers list but sent mail will bounce back without having subscribed to the list first.<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://public.kitware.com/dashboard.php?name=vtk<br />
<br />
VTK uses Dart to perform builds, run tests, and generate dashboards. You<br />
can find more information about Dart at: http://public.kitware.com/Dart/<br />
<br />
You can help improve the quality of VTK by supplying the authors with<br />
Tcl scripts that can be used as or turned into regression tests. A good<br />
regression test will:<br />
<br />
# Cover code that is not already covered.<br />
# Illustrate a bug that is occuring now or that has occurred in the past.<br />
# Use data that is on the 2nd Edition book CDROM or use "small" data files or use no data at all.<br />
# Optionally, produce an interesting result. <br />
<br />
Currently almost all regression tests are written in Tcl.<br />
<br />
Please send your Tcl regression tests to:<br />
mailto:wlorens1@mail.nycap.rr.com<br />
<br />
Bill will evaluate them for applicability and integrate them into the<br />
nightly test process.<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are five things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and work through the examples (there are 400-500 examples). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled "How to ask questions the smart<br />
way". Read it here:<br />
<br />
http://www.catb.org/~esr/faqs/smart-questions.html<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Avoid HTML emails.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
bacause the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Developement]]<br />
<br />
=== Accessing VTK CVS from behind a firewall ===<br />
<br />
Use the sourceforge project:<br />
<br />
http://cvsgrab.sourceforge.net/<br />
<br />
Just download the script and type something like:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xx<br />
<br />
(Thanks to Ingo H. de Boer)<br />
<br />
Also cvsgrab support the following option to access a particular branch:<br />
<br />
-tag <version tag> [optional] The version tag of the files to download<br />
<br />
For example to get the latest 4.4 branch:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xxx<br />
-tag release-4-4<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# 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.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
http://www.google.com/url?sa=D&q=http%3A%2F%2Fpublic.kitware.com%2Fpipermail%2Fvtkusers%2F2003-October%2F070054.html<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# 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''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
For a more elaborate DICOM library that supports compressed jpeg, you might try [http://www.creatis.insa-lyon.fr/Public/Gdcm/ Gdcm].<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
1) Using ReleaseDataFlag<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
2) Use ImmediateModeRendering<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
3) Use triangle strips via vtkStripper.<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
4) Use a different filter or mapper<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use STL. However, the following policy<br />
applies.<br />
<br />
# 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.<br />
# 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.<br />
# Include the VTK wrapper header files: vtkstd/map instead of map.<br />
# Use the vtkstd:: namespace to refer to STL classes and functions.<br />
<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| MPEG2 || || vtkMPEG2Writer<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows and Mac workstations.<br />
<br />
=== What Graphics Cards work with VTK ===<br />
<br />
VTK uses OpenGL to perform almost all of its rendering and some graphics cards/drivers have better support for OpenGL than others. This is not a listing of what cards perform well. It is a listing of what cards actually produce correct results. Here is a list of cards and their status roughly in best to worst order.<br />
<br />
* Any Nvidia desktop card on Windows -- 100% compatible<br /> <br />
* Any ATI desktop cards on Windows -- 100% compatible<br /><br />
* Mesa -- most releases pass all VTK tests<br /><br />
* Microsoft Software OpenGL -- passes all VTK tests but does have a couple bugs<br /><br />
* Mac graphics cards -- these usually pass all VTK tests. Older cards may have some issues, for example, the ATI Rage 128 Pro does not support textures larger than 1024x1024.<br /><br />
* Non-linux UNIX cards (Sun HP SGI) -- These generally work<br /><br />
* Any Nvidia card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Any ATI card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Nvidia laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests<br /><br />
* ATI laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests (e.g. [http://public.kitware.com/pipermail/vtkusers/2004-August/075966.html ATI Mobility Radeon 9600])<br /><br />
* Intel Extreme Graphics -- fails some VTK tests<br /><br />
<br />
=== How do I build the examples on the PC running Windows? ===<br />
<br />
Since building the C++ examples on the PC isn't all that easy, here are<br />
some instructions from Jack McInerney.<br />
<br />
Steps for creating a VTK C++ project 8/14/96<br />
<br />
This is based on what I learned creating a project to run the Mace<br />
example. These steps allowed me to successfully built and run this example.<br />
<br />
# Create a console project (File, New, then select Console application).<br />
# Add the files of interest to the project. (e.g., Mace.cxx)<br />
# Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies<br /> 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<br />
# 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).<br />
# 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 <br /> This is a self extracting archive which contains these files. Simply place them in your windows system directory.<br />
# Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless<br /><br />
<br />
When you go to run the program, it will bomb out unless it can find 2<br />
DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the<br />
project directory or the C:\WINDOWS directory. These files are supplied<br />
on the vtk CD-ROM (in the vtk\bin directory).<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
vtk builds on 64 bit systems, that is, systems where sizeof(void*) is 64 bits. However, parts of the vtk codebase are not 64 bit clean and so runtime problems are likely if that code is used.<br />
<br />
===== General =====<br />
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.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work reasonably with 64 bit Cocoa.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== What size swap space should I use on a PC? ===<br />
<br />
Building vtk on the PC requires a significant amount of memory (at least<br />
when using Visual C++)... but the final product is nice and compact. To<br />
build vtk on the PC, we recommend setting the min/max swap space to at<br />
least 400MB/500MB (depending on how much RAM you have... the sum of RAM<br />
and swap space should be roughly 500+ MB).<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
Struggled a few hours to get VTK to do offscreen rendering. I use it to<br />
batch process medical images. Without actually producing output on the<br />
screen, I still print resulting images in a report to easily review the<br />
results of an experiment.<br />
<br />
Here is how I solved this problem for VTK version 4.2.2.<br />
<br />
1. Download Mesa-4.0.4 source<br />
<br />
Modify Mesa-4.0.4/Make-config in the 'linux:' target the following vars:<br />
<br />
GL_LIB = libVTKMesaGL.so<br />
GLU_LIB = libVTKMesaGLU.so<br />
GLUT_LIB = libVTKMesaglut.so<br />
GLW_LIB = libVTKMesaGLw.so<br />
OSMESA_LIB = libOSVTKMesa.so<br />
<br />
In Mesa 6.2.1 you need to edit Mesa/configs/default instead:<br />
<br />
# Library names (base name)<br />
GL_LIB = VTKMesaGL<br />
GLU_LIB = VTKMesaGLU<br />
GLUT_LIB = VTKMesaglut<br />
GLW_LIB = VTKMesaGLw<br />
OSMESA_LIB = VTKMesaOSMesa<br />
<br />
<br />
And then export this env var:<br />
<br />
export 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"<br />
<br />
then<br />
<br />
For Mesa 4.0.4<br />
<br />
make -f Makefile.X11 linux <br />
cp Mesa-4.0.4/lib/* /data/usr/mesa404/lib/<br />
<br />
in Mesa 6.2.1:<br />
<br />
make linux-x86<br />
make install<br />
(I generally use /opt/VTKMesa/*)<br />
<br />
I use 'VTKMesa' name extension to avoid conflicts with my RH9.0 libs<br />
(especially OSMesa lib in XFree!). I'm using shared libraries, because<br />
that allows me to use dynamic libs from VTK and not the vtk program<br />
itself without explicitly having to load VTKMesaGL with my app. I copied<br />
the 'VTKMesa' libs in /data/usr/mesa404/lib/, but any odd place probably<br />
will work. Avoid /usr/lib /usr/local/lib for now.<br />
<br />
2. Follow normal instructions to get a proper working vtk, then<br />
<br />
ccmake <br />
<br />
with the following options:<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
| VTK_USE_MANGLED_MESA || ON<br />
|-<br />
| MANGLED_MESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_MESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaGL.so<br />
|-<br />
| MANGLED_OSMESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_OSMESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaOSMesa.so<br />
|-<br />
| OPENGL_xmesa_INCLUDE_DIR || /data/usr/mesa404/include<br />
|}<br />
<br />
test using /data/prog/VTK-4.2.2/Examples/MangledMesa/Tcl scripts<br />
<br />
<br />
If you're doing things on UNIX, you should also look at [[VTK Classes]]. It has links to RenderWindow objects that are probably easier to use than rebuilding VTK with Mesa.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
On Mac OS X, there are (at least) two kinds of executables:<br />
* [http://developer.apple.com/documentation/MacOSX/Conceptual/BPInternational/Articles/InternatSupport.html#//apple_ref/doc/uid/20000278-73764 Application Bundles]<br />
* plain UNIX executables<br />
<br />
For a program to be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction) it really should be an Application Bundle. If a plain UNIX executable tries, there will be various bugs, such as keyboard and mouse events not working reliably.<br />
<br />
Many, but not all, of the example VTK applications are built as plain UNIX executables, and thus have these problems. This is [http://www.vtk.org/Bug/bug.php?op=show&bugid=2025 VTK bug 2025].<br />
<br />
When you build your own VTK application, it is best to make it in the form of an Application Bundle. With CMake 2.0.5 or later, simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an Application Bundle (perhaps because your app needs command line parameters) you might be able to avoid the above problems by adding an [http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/ConfigFiles.html#//apple_ref/doc/uid/20002091-SW1 __info_plist section] to your Mach-O executable. If you succeed, please post to the VTK list.<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.4 and older, the short answer is "no".<br />
<br />
For VTK CVS the short answer is "mostly". You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. The usual settings are:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk <br />
<br />
This will result in a Universal build. However, there may be runtime bugs due to VTK's use of TRY_RUN. Work is being done to improve this situation.<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
=== How can a user process access more than 2 GB of ram in 32-bit Windows? ===<br />
<br />
By default on Windows, the most memory that a user process can access is 2 GB, no matter how much RAM you have installed in your system. With Windows XP Professional you can make it possible for a process to use up to 3 GB of memory by doing two things:<br />
<br />
1) Modify the boot parameters in boot.ini (on my 32 bit WinXP Pro machine, it's in: "C:\boot.ini") to tell the operating system that you want user processes to have access to up to 3GB of RAM (This is a really important file, and if you don't know what you are doing, stop reading this and go back to work!). This is done by adding the /3GB flag to the line of the file that tells the boot loader where the operating system is. My boot.ini file looks like:<br />
<br />
[boot loader]<br />
timeout=30<br />
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS<br />
[operating systems]<br />
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /3GB<br />
<br />
This is a very bad file to make mistakes on, so don't - it may be very difficult to repair your computer to boot if you mess up this file. There is a nice description of this in the Microsoft article <br />
[http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx Memory Support and Windows Operating Systems].<br />
<br />
2) The other thing that you need to do is make your executable LARGEADDRESSAWARE. Assuming that you have a Windows binary that you want to try this on, you can use the 'editbin' utility that comes with Visual Studio to change the setting of one bit (the IMAGE_FILE_LARGE_ADDRESS_AWARE bit) in the image header of the executable. For a program 'prog.exe' you can make the change by<br />
<br />
editbin /LARGEADDRESSAWARE prog.exe<br />
<br />
Of course, depending on how your program handles memory you might find that it crashes when you try to use the extra memory, but that's a separate issue. If you are compiling your program with a version of Visual Studio you should be able to find the switch to make your program /LARGEADDRESSAWARE.<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes in VTK between 3.2 and 4.0 ===<br />
<br />
* 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.<br />
<br />
* 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<br />
<br />
* Added special methods to data arrays to replace methods like<br />
<br />
tc SetTCoord i x y 0<br />
<br />
or<br />
<br />
vc SetVector i vx vy vz<br />
<br />
in interpreted languages (Tcl, Python, Java). Use:<br />
<br />
tc SetTuple2 i x y<br />
<br />
or<br />
<br />
vc SetTuple3 i vx vy vz<br />
<br />
* 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.<br />
<br />
* vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.<br />
<br />
* 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.<br />
<br />
* 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).<br />
<br />
* The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.<br />
<br />
* Support for reading and writing PGM and JPEG images has been included.<br />
<br />
* 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.<br />
<br />
* 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 Imaging 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.<br />
<br />
* 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.<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* 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.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* 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.<br />
<br />
* 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:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== How do I upgrade my existing C++ code from 3.2 to 4.x? ===<br />
<br />
This is (a corrected version of) an email that was posted to vtkusers.<br />
Please feel free to correct or add anything.<br />
<br />
{| cellspacing="3" <br />
|- valign="top"<br />
|width="55%" bgcolor="#f0f0ff" style="border:1px solid #ffc9c9;padding:1em;padding-top:0.5em;"|<br />
<br />
I've just ported my medium-sized (40K lines) application from vtk3.2 to<br />
vtk4.x. I thought I would share my experiences with you, in case there<br />
were people out there contemplating it but a bit scared.<br />
<br />
One source of information for upgrading code is:<br />
<br />
http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the<br />
script in the zip file.<br />
<br />
So,<br />
<br />
I switched all my include directories to the new VTK ones and<br />
recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and<br />
vtkTCoords which have both been removed. Where I was using single value<br />
scalars, like this:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetNumberOfScalars(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetScalar(i,2.3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *scalars = vtkFloatArray::New();<br />
scalars->SetNumberOfComponents(1);<br />
scalars->SetNumberOfTuples(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetTuple1(i,2.3);<br />
...<br />
<br />
OK so far, far fewer errors.<br />
<br />
Where I had 2D texture coordinates:<br />
<br />
vtkTCoords *tcoords = vtkTCoords::New();<br />
tcoords->SetNumberOfTCoords(N);<br />
...<br />
float p[3];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTCoord(i,p);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *tcoords = vtkFloatArray::New();<br />
tcoords->SetNumberOfComponents(2);<br />
tcoords->SetNumberOfTuples(N);<br />
...<br />
float p[2];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTuple(i,p);<br />
....<br />
<br />
All well and good, still fewer errors. Make sure you call<br />
SetNumberOfComponents *before* SetNumberOfTuples else you'll get<br />
problems (I did!).<br />
<br />
Where I was creating 0-255 image data and had been using:<br />
<br />
vtkScalars* scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
...<br />
<br />
Going well!<br />
<br />
When creating RGB images, I had been using:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfScalars(X*Y);<br />
...<br />
scalars->SetActiveComponent(0);<br />
scalars->SetScalar(i,val1);<br />
scalars->SetActiveComponent(1);<br />
scalars->SetScalar(i,val2);<br />
scalars->SetActiveComponent(2);<br />
scalars->SetScalar(i,val3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfTuples(X*Y);<br />
...<br />
scalars->SetComponent(i,0,val1);<br />
scalars->SetComponent(i,1,val2);<br />
scalars->SetComponent(i,2,val3);<br />
...<br />
<br />
My remaining errors concerned vtkWin32OffscreenRenderWindow that has<br />
been removed. Where I had been using:<br />
<br />
vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New();<br />
offscreen->SetOffScreenRendering(1);<br />
...<br />
<br />
All done. I'd had to throw in some #include "vtkFloatArray.h" and things<br />
like that of course. Zero compile errors.<br />
<br />
Had to remember to link against the new vtk lib files, so I removed<br />
<br />
vtkdll.lib <br />
<br />
and added<br />
<br />
vtkCommon.lib<br />
vtkGraphics.lib<br />
<br />
etc.<br />
<br />
Zero link errors. My program is up and running again, no apparant<br />
problems. Plus now I can use all the new features of vtk4. (And I'm sure<br />
it's faster but maybe that's my imagination.)<br />
<br />
All this took me about three hours.<br />
<br />
Bye!<br />
<br />
Tim.<br />
|}<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was releaseed in February 2003. VTK 4.4 (which was an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, 5.0.3 in March 2007, and 5.0.4 in January 2008.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# 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.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* 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.<br />
#* 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.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* 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.<br />
* 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).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* 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. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* 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.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
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.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== Using Volume Rendering in VTK ===<br />
<br />
I recently updated my VTK CVS version. And my c++ code that use to work fine are now complaining about:<br />
<br />
undefined reference to `vtkUnstructuredGridAlgorithm::SetInput(vtkDataObject*)'<br />
undefined reference to `vtkUnstructuredGridAlgorithm::GetOutput()' <br />
<br />
There is now a new subfolder and a new option to enable building the VolumeRendering library. You have to turn VTK_USE_VOLUMERENDERING to ON in order to use it. Also make sure that your executable is linking properly to this new library:<br />
<br />
ADD_EXECUTABLE(foo foo.cxx)<br />
TARGET_LINK_LIBRARIES(foo vtkVolumeRendering)<br />
<br />
== OpenGL requirements ==<br />
<br />
=== Terminology ===<br />
<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
<br />
==== Linux/Unix ====<br />
<br />
Two ways:<br />
<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
<br />
* vendor specific tool<br />
<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or<br />
hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
== Miscellaneous questions ==<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. We think it's pretty reasonable. We do restrict the<br />
distribution of modified code. This is primarily a revision control<br />
issue. We don't want a bunch of renegade vtks running around without us<br />
having some idea why the changes were made and giving us a chance to<br />
incorporate them into the general release.<br />
<br />
The text of the VTK copyright is available [http://www.vtk.org/copyright.php here].<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
=== What is the deal with the patents ===<br />
<br />
As the copyright mentions there are some patents used in VTK. If you use<br />
any code in the Patented/ directory for commercial application you<br />
should contact the patent holder and obtain a license.<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by General Electric Company: vtkDecimate, vtkMarchingCubes,<br />
vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface.<br />
The GE contact is:<br />
<br />
Carl B. Horton<br />
Sr. Counsel, Intellectual Property<br />
3000 N. Grandview Blvd., W-710<br />
Waukesha, WI 53188<br />
Phone: (262) 513-4022<br />
E-Mail: mailto:Carl.Horton@med.ge.com<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by Kitware, Inc.: vtkGridSynchronizedTemplates3D,<br />
vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and<br />
vtkSynchronizedTemplates3D. The Kitware contact is:<br />
<br />
Ken Martin<br />
Kitware<br />
28 Corporate Drive, Suite 204,<br />
Clifton Park, NY 12065<br />
Phone:1-518-371-3971<br />
E-Mail: mailto:kitware@kitware.com<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=11436VTK/FAQ2008-01-23T15:09:08Z<p>Seanmcbride: /* Can VTK be built as a Universal Binary on Mac OS X? */</p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk is 5.0.4 (released on 2008-01-22). This release is available at:<br />
<br />
http://www.vtk.org/files/release/5.0/<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly/<br />
<br />
See http://www.vtk.org/get-software.php for more information.<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesisitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Can I contribute money? ===<br />
<br />
Please don't send money. Not that we think you're going to send in<br />
unsolicited money. But if you were thinking about it, stop. It would<br />
just complicate our lives and make for all sorts of tax problems.<br />
<br />
(Note: if you are a company or funding institution, and would like to fund<br />
features or development, please contact Kitware http://www.kitware.com .)<br />
<br />
=== Is there a mailing list or Usenet newsgroup for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
There is also a newsgroup that mirrors the mailinglist. At this point it<br />
seems that mirror is down. Mail to the mailinglist used to be posted the<br />
newsgroup, but posts on the newsgroup were not sent to the mailinglist.<br />
The newsgroup was located at:<br />
news://scully.esat.kuleuven.ac.be/vtk.mailinglist<br />
<br />
http://www.gmane.org is a bidirectional mail-to-news gateway that carries the vtkusers mailing list. Its located here: news://news.gmane.org/gmane.comp.lib.vtk.user or here: http://news.gmane.org/gmane.comp.lib.vtk.user. vtkusers mails have been archived since April 2002 and they never expire. You can read and send mails to the vtkusers list but sent mail will bounce back without having subscribed to the list first.<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://public.kitware.com/dashboard.php?name=vtk<br />
<br />
VTK uses Dart to perform builds, run tests, and generate dashboards. You<br />
can find more information about Dart at: http://public.kitware.com/Dart/<br />
<br />
You can help improve the quality of VTK by supplying the authors with<br />
Tcl scripts that can be used as or turned into regression tests. A good<br />
regression test will:<br />
<br />
# Cover code that is not already covered.<br />
# Illustrate a bug that is occuring now or that has occurred in the past.<br />
# Use data that is on the 2nd Edition book CDROM or use "small" data files or use no data at all.<br />
# Optionally, produce an interesting result. <br />
<br />
Currently almost all regression tests are written in Tcl.<br />
<br />
Please send your Tcl regression tests to:<br />
mailto:wlorens1@mail.nycap.rr.com<br />
<br />
Bill will evaluate them for applicability and integrate them into the<br />
nightly test process.<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are five things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and work through the examples (there are 400-500 examples). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled "How to ask questions the smart<br />
way". Read it here:<br />
<br />
http://www.catb.org/~esr/faqs/smart-questions.html<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Avoid HTML emails.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
bacause the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Developement]]<br />
<br />
=== Accessing VTK CVS from behind a firewall ===<br />
<br />
Use the sourceforge project:<br />
<br />
http://cvsgrab.sourceforge.net/<br />
<br />
Just download the script and type something like:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xx<br />
<br />
(Thanks to Ingo H. de Boer)<br />
<br />
Also cvsgrab support the following option to access a particular branch:<br />
<br />
-tag <version tag> [optional] The version tag of the files to download<br />
<br />
For example to get the latest 4.4 branch:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xxx<br />
-tag release-4-4<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# 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.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
http://www.google.com/url?sa=D&q=http%3A%2F%2Fpublic.kitware.com%2Fpipermail%2Fvtkusers%2F2003-October%2F070054.html<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# 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''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
For a more elaborate DICOM library that supports compressed jpeg, you might try [http://www.creatis.insa-lyon.fr/Public/Gdcm/ Gdcm].<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
1) Using ReleaseDataFlag<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
2) Use ImmediateModeRendering<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
3) Use triangle strips via vtkStripper.<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
4) Use a different filter or mapper<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use STL. However, the following policy<br />
applies.<br />
<br />
# 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.<br />
# 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.<br />
# Include the VTK wrapper header files: vtkstd/map instead of map.<br />
# Use the vtkstd:: namespace to refer to STL classes and functions.<br />
<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| MPEG2 || || vtkMPEG2Writer<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows and Mac workstations.<br />
<br />
=== What Graphics Cards work with VTK ===<br />
<br />
VTK uses OpenGL to perform almost all of its rendering and some graphics cards/drivers have better support for OpenGL than others. This is not a listing of what cards perform well. It is a listing of what cards actually produce correct results. Here is a list of cards and their status roughly in best to worst order.<br />
<br />
* Any Nvidia desktop card on Windows -- 100% compatible<br /> <br />
* Any ATI desktop cards on Windows -- 100% compatible<br /><br />
* Mesa -- most releases pass all VTK tests<br /><br />
* Microsoft Software OpenGL -- passes all VTK tests but does have a couple bugs<br /><br />
* Mac graphics cards -- these usually pass all VTK tests. Older cards may have some issues, for example, the ATI Rage 128 Pro does not support textures larger than 1024x1024.<br /><br />
* Non-linux UNIX cards (Sun HP SGI) -- These generally work<br /><br />
* Any Nvidia card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Any ATI card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Nvidia laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests<br /><br />
* ATI laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests (e.g. [http://public.kitware.com/pipermail/vtkusers/2004-August/075966.html ATI Mobility Radeon 9600])<br /><br />
* Intel Extreme Graphics -- fails some VTK tests<br /><br />
<br />
=== How do I build the examples on the PC running Windows? ===<br />
<br />
Since building the C++ examples on the PC isn't all that easy, here are<br />
some instructions from Jack McInerney.<br />
<br />
Steps for creating a VTK C++ project 8/14/96<br />
<br />
This is based on what I learned creating a project to run the Mace<br />
example. These steps allowed me to successfully built and run this example.<br />
<br />
# Create a console project (File, New, then select Console application).<br />
# Add the files of interest to the project. (e.g., Mace.cxx)<br />
# Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies<br /> 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<br />
# 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).<br />
# 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 <br /> This is a self extracting archive which contains these files. Simply place them in your windows system directory.<br />
# Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless<br /><br />
<br />
When you go to run the program, it will bomb out unless it can find 2<br />
DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the<br />
project directory or the C:\WINDOWS directory. These files are supplied<br />
on the vtk CD-ROM (in the vtk\bin directory).<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
vtk builds on 64 bit systems, that is, systems where sizeof(void*) is 64 bits. However, parts of the vtk codebase are not 64 bit clean and so runtime problems are likely if that code is used.<br />
<br />
===== General =====<br />
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.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work reasonably with 64 bit Cocoa.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== What size swap space should I use on a PC? ===<br />
<br />
Building vtk on the PC requires a significant amount of memory (at least<br />
when using Visual C++)... but the final product is nice and compact. To<br />
build vtk on the PC, we recommend setting the min/max swap space to at<br />
least 400MB/500MB (depending on how much RAM you have... the sum of RAM<br />
and swap space should be roughly 500+ MB).<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
Struggled a few hours to get VTK to do offscreen rendering. I use it to<br />
batch process medical images. Without actually producing output on the<br />
screen, I still print resulting images in a report to easily review the<br />
results of an experiment.<br />
<br />
Here is how I solved this problem for VTK version 4.2.2.<br />
<br />
1. Download Mesa-4.0.4 source<br />
<br />
Modify Mesa-4.0.4/Make-config in the 'linux:' target the following vars:<br />
<br />
GL_LIB = libVTKMesaGL.so<br />
GLU_LIB = libVTKMesaGLU.so<br />
GLUT_LIB = libVTKMesaglut.so<br />
GLW_LIB = libVTKMesaGLw.so<br />
OSMESA_LIB = libOSVTKMesa.so<br />
<br />
In Mesa 6.2.1 you need to edit Mesa/configs/default instead:<br />
<br />
# Library names (base name)<br />
GL_LIB = VTKMesaGL<br />
GLU_LIB = VTKMesaGLU<br />
GLUT_LIB = VTKMesaglut<br />
GLW_LIB = VTKMesaGLw<br />
OSMESA_LIB = VTKMesaOSMesa<br />
<br />
<br />
And then export this env var:<br />
<br />
export 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"<br />
<br />
then<br />
<br />
For Mesa 4.0.4<br />
<br />
make -f Makefile.X11 linux <br />
cp Mesa-4.0.4/lib/* /data/usr/mesa404/lib/<br />
<br />
in Mesa 6.2.1:<br />
<br />
make linux-x86<br />
make install<br />
(I generally use /opt/VTKMesa/*)<br />
<br />
I use 'VTKMesa' name extension to avoid conflicts with my RH9.0 libs<br />
(especially OSMesa lib in XFree!). I'm using shared libraries, because<br />
that allows me to use dynamic libs from VTK and not the vtk program<br />
itself without explicitly having to load VTKMesaGL with my app. I copied<br />
the 'VTKMesa' libs in /data/usr/mesa404/lib/, but any odd place probably<br />
will work. Avoid /usr/lib /usr/local/lib for now.<br />
<br />
2. Follow normal instructions to get a proper working vtk, then<br />
<br />
ccmake <br />
<br />
with the following options:<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
| VTK_USE_MANGLED_MESA || ON<br />
|-<br />
| MANGLED_MESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_MESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaGL.so<br />
|-<br />
| MANGLED_OSMESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_OSMESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaOSMesa.so<br />
|-<br />
| OPENGL_xmesa_INCLUDE_DIR || /data/usr/mesa404/include<br />
|}<br />
<br />
test using /data/prog/VTK-4.2.2/Examples/MangledMesa/Tcl scripts<br />
<br />
<br />
If you're doing things on UNIX, you should also look at [[VTK Classes]]. It has links to RenderWindow objects that are probably easier to use than rebuilding VTK with Mesa.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
On Mac OS X, there are (at least) two kinds of executables:<br />
* [http://developer.apple.com/documentation/MacOSX/Conceptual/BPInternational/Articles/InternatSupport.html#//apple_ref/doc/uid/20000278-73764 Application Bundles]<br />
* plain UNIX executables<br />
<br />
For a program to be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction) it really should be an Application Bundle. If a plain UNIX executable tries, there will be various bugs, such as keyboard and mouse events not working reliably.<br />
<br />
Many, but not all, of the example VTK applications are built as plain UNIX executables, and thus have these problems. This is [http://www.vtk.org/Bug/bug.php?op=show&bugid=2025 VTK bug 2025].<br />
<br />
When you build your own VTK application, it is best to make it in the form of an Application Bundle. With CMake 2.0.5 or later, simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an Application Bundle (perhaps because your app needs command line parameters) you might be able to avoid the above problems by adding an [http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/ConfigFiles.html#//apple_ref/doc/uid/20002091-SW1 __info_plist section] to your Mach-O executable. If you succeed, please post to the VTK list.<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.4 and older, the short answer is "no".<br />
<br />
For VTK CVS the short answer is "mostly". You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. The usual settings are:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk <br />
<br />
This will result in a Universal build. However, there may be runtime bugs due to VTK's use of TRY_RUN. Work is being done to improve this situation.<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
=== How can a user process access more than 2 GB of ram in 32-bit Windows? ===<br />
<br />
By default on Windows, the most memory that a user process can access is 2 GB, no matter how much RAM you have installed in your system. With Windows XP Professional you can make it possible for a process to use up to 3 GB of memory by doing two things:<br />
<br />
1) Modify the boot parameters in boot.ini (on my 32 bit WinXP Pro machine, it's in: "C:\boot.ini") to tell the operating system that you want user processes to have access to up to 3GB of RAM (This is a really important file, and if you don't know what you are doing, stop reading this and go back to work!). This is done by adding the /3GB flag to the line of the file that tells the boot loader where the operating system is. My boot.ini file looks like:<br />
<br />
[boot loader]<br />
timeout=30<br />
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS<br />
[operating systems]<br />
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /3GB<br />
<br />
This is a very bad file to make mistakes on, so don't - it may be very difficult to repair your computer to boot if you mess up this file. There is a nice description of this in the Microsoft article <br />
[http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx Memory Support and Windows Operating Systems].<br />
<br />
2) The other thing that you need to do is make your executable LARGEADDRESSAWARE. Assuming that you have a Windows binary that you want to try this on, you can use the 'editbin' utility that comes with Visual Studio to change the setting of one bit (the IMAGE_FILE_LARGE_ADDRESS_AWARE bit) in the image header of the executable. For a program 'prog.exe' you can make the change by<br />
<br />
editbin /LARGEADDRESSAWARE prog.exe<br />
<br />
Of course, depending on how your program handles memory you might find that it crashes when you try to use the extra memory, but that's a separate issue. If you are compiling your program with a version of Visual Studio you should be able to find the switch to make your program /LARGEADDRESSAWARE.<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes in VTK between 3.2 and 4.0 ===<br />
<br />
* 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.<br />
<br />
* 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<br />
<br />
* Added special methods to data arrays to replace methods like<br />
<br />
tc SetTCoord i x y 0<br />
<br />
or<br />
<br />
vc SetVector i vx vy vz<br />
<br />
in interpreted languages (Tcl, Python, Java). Use:<br />
<br />
tc SetTuple2 i x y<br />
<br />
or<br />
<br />
vc SetTuple3 i vx vy vz<br />
<br />
* 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.<br />
<br />
* vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.<br />
<br />
* 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.<br />
<br />
* 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).<br />
<br />
* The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.<br />
<br />
* Support for reading and writing PGM and JPEG images has been included.<br />
<br />
* 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.<br />
<br />
* 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 Imaging 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.<br />
<br />
* 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.<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* 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.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* 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.<br />
<br />
* 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:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== How do I upgrade my existing C++ code from 3.2 to 4.x? ===<br />
<br />
This is (a corrected version of) an email that was posted to vtkusers.<br />
Please feel free to correct or add anything.<br />
<br />
{| cellspacing="3" <br />
|- valign="top"<br />
|width="55%" bgcolor="#f0f0ff" style="border:1px solid #ffc9c9;padding:1em;padding-top:0.5em;"|<br />
<br />
I've just ported my medium-sized (40K lines) application from vtk3.2 to<br />
vtk4.x. I thought I would share my experiences with you, in case there<br />
were people out there contemplating it but a bit scared.<br />
<br />
One source of information for upgrading code is:<br />
<br />
http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the<br />
script in the zip file.<br />
<br />
So,<br />
<br />
I switched all my include directories to the new VTK ones and<br />
recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and<br />
vtkTCoords which have both been removed. Where I was using single value<br />
scalars, like this:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetNumberOfScalars(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetScalar(i,2.3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *scalars = vtkFloatArray::New();<br />
scalars->SetNumberOfComponents(1);<br />
scalars->SetNumberOfTuples(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetTuple1(i,2.3);<br />
...<br />
<br />
OK so far, far fewer errors.<br />
<br />
Where I had 2D texture coordinates:<br />
<br />
vtkTCoords *tcoords = vtkTCoords::New();<br />
tcoords->SetNumberOfTCoords(N);<br />
...<br />
float p[3];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTCoord(i,p);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *tcoords = vtkFloatArray::New();<br />
tcoords->SetNumberOfComponents(2);<br />
tcoords->SetNumberOfTuples(N);<br />
...<br />
float p[2];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTuple(i,p);<br />
....<br />
<br />
All well and good, still fewer errors. Make sure you call<br />
SetNumberOfComponents *before* SetNumberOfTuples else you'll get<br />
problems (I did!).<br />
<br />
Where I was creating 0-255 image data and had been using:<br />
<br />
vtkScalars* scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
...<br />
<br />
Going well!<br />
<br />
When creating RGB images, I had been using:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfScalars(X*Y);<br />
...<br />
scalars->SetActiveComponent(0);<br />
scalars->SetScalar(i,val1);<br />
scalars->SetActiveComponent(1);<br />
scalars->SetScalar(i,val2);<br />
scalars->SetActiveComponent(2);<br />
scalars->SetScalar(i,val3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfTuples(X*Y);<br />
...<br />
scalars->SetComponent(i,0,val1);<br />
scalars->SetComponent(i,1,val2);<br />
scalars->SetComponent(i,2,val3);<br />
...<br />
<br />
My remaining errors concerned vtkWin32OffscreenRenderWindow that has<br />
been removed. Where I had been using:<br />
<br />
vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New();<br />
offscreen->SetOffScreenRendering(1);<br />
...<br />
<br />
All done. I'd had to throw in some #include "vtkFloatArray.h" and things<br />
like that of course. Zero compile errors.<br />
<br />
Had to remember to link against the new vtk lib files, so I removed<br />
<br />
vtkdll.lib <br />
<br />
and added<br />
<br />
vtkCommon.lib<br />
vtkGraphics.lib<br />
<br />
etc.<br />
<br />
Zero link errors. My program is up and running again, no apparant<br />
problems. Plus now I can use all the new features of vtk4. (And I'm sure<br />
it's faster but maybe that's my imagination.)<br />
<br />
All this took me about three hours.<br />
<br />
Bye!<br />
<br />
Tim.<br />
|}<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was releaseed in February 2003. VTK 4.4 (which is an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, and 5.0.3 in March 2007.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# 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.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* 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.<br />
#* 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.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* 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.<br />
* 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).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* 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. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* 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.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
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.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== Using Volume Rendering in VTK ===<br />
<br />
I recently updated my VTK CVS version. And my c++ code that use to work fine are now complaining about:<br />
<br />
undefined reference to `vtkUnstructuredGridAlgorithm::SetInput(vtkDataObject*)'<br />
undefined reference to `vtkUnstructuredGridAlgorithm::GetOutput()' <br />
<br />
There is now a new subfolder and a new option to enable building the VolumeRendering library. You have to turn VTK_USE_VOLUMERENDERING to ON in order to use it. Also make sure that your executable is linking properly to this new library:<br />
<br />
ADD_EXECUTABLE(foo foo.cxx)<br />
TARGET_LINK_LIBRARIES(foo vtkVolumeRendering)<br />
<br />
== OpenGL requirements ==<br />
<br />
=== Terminology ===<br />
<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
<br />
==== Linux/Unix ====<br />
<br />
Two ways:<br />
<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
<br />
* vendor specific tool<br />
<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or<br />
hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
== Miscellaneous questions ==<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. We think it's pretty reasonable. We do restrict the<br />
distribution of modified code. This is primarily a revision control<br />
issue. We don't want a bunch of renegade vtks running around without us<br />
having some idea why the changes were made and giving us a chance to<br />
incorporate them into the general release.<br />
<br />
The text of the VTK copyright is available [http://www.vtk.org/copyright.php here].<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
=== What is the deal with the patents ===<br />
<br />
As the copyright mentions there are some patents used in VTK. If you use<br />
any code in the Patented/ directory for commercial application you<br />
should contact the patent holder and obtain a license.<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by General Electric Company: vtkDecimate, vtkMarchingCubes,<br />
vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface.<br />
The GE contact is:<br />
<br />
Carl B. Horton<br />
Sr. Counsel, Intellectual Property<br />
3000 N. Grandview Blvd., W-710<br />
Waukesha, WI 53188<br />
Phone: (262) 513-4022<br />
E-Mail: mailto:Carl.Horton@med.ge.com<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by Kitware, Inc.: vtkGridSynchronizedTemplates3D,<br />
vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and<br />
vtkSynchronizedTemplates3D. The Kitware contact is:<br />
<br />
Ken Martin<br />
Kitware<br />
28 Corporate Drive, Suite 204,<br />
Clifton Park, NY 12065<br />
Phone:1-518-371-3971<br />
E-Mail: mailto:kitware@kitware.com<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=11435VTK/FAQ2008-01-23T15:08:58Z<p>Seanmcbride: /* What is the current release? */</p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk is 5.0.4 (released on 2008-01-22). This release is available at:<br />
<br />
http://www.vtk.org/files/release/5.0/<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly/<br />
<br />
See http://www.vtk.org/get-software.php for more information.<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesisitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Can I contribute money? ===<br />
<br />
Please don't send money. Not that we think you're going to send in<br />
unsolicited money. But if you were thinking about it, stop. It would<br />
just complicate our lives and make for all sorts of tax problems.<br />
<br />
(Note: if you are a company or funding institution, and would like to fund<br />
features or development, please contact Kitware http://www.kitware.com .)<br />
<br />
=== Is there a mailing list or Usenet newsgroup for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
There is also a newsgroup that mirrors the mailinglist. At this point it<br />
seems that mirror is down. Mail to the mailinglist used to be posted the<br />
newsgroup, but posts on the newsgroup were not sent to the mailinglist.<br />
The newsgroup was located at:<br />
news://scully.esat.kuleuven.ac.be/vtk.mailinglist<br />
<br />
http://www.gmane.org is a bidirectional mail-to-news gateway that carries the vtkusers mailing list. Its located here: news://news.gmane.org/gmane.comp.lib.vtk.user or here: http://news.gmane.org/gmane.comp.lib.vtk.user. vtkusers mails have been archived since April 2002 and they never expire. You can read and send mails to the vtkusers list but sent mail will bounce back without having subscribed to the list first.<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://public.kitware.com/dashboard.php?name=vtk<br />
<br />
VTK uses Dart to perform builds, run tests, and generate dashboards. You<br />
can find more information about Dart at: http://public.kitware.com/Dart/<br />
<br />
You can help improve the quality of VTK by supplying the authors with<br />
Tcl scripts that can be used as or turned into regression tests. A good<br />
regression test will:<br />
<br />
# Cover code that is not already covered.<br />
# Illustrate a bug that is occuring now or that has occurred in the past.<br />
# Use data that is on the 2nd Edition book CDROM or use "small" data files or use no data at all.<br />
# Optionally, produce an interesting result. <br />
<br />
Currently almost all regression tests are written in Tcl.<br />
<br />
Please send your Tcl regression tests to:<br />
mailto:wlorens1@mail.nycap.rr.com<br />
<br />
Bill will evaluate them for applicability and integrate them into the<br />
nightly test process.<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are five things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and work through the examples (there are 400-500 examples). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled "How to ask questions the smart<br />
way". Read it here:<br />
<br />
http://www.catb.org/~esr/faqs/smart-questions.html<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Avoid HTML emails.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
bacause the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Developement]]<br />
<br />
=== Accessing VTK CVS from behind a firewall ===<br />
<br />
Use the sourceforge project:<br />
<br />
http://cvsgrab.sourceforge.net/<br />
<br />
Just download the script and type something like:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xx<br />
<br />
(Thanks to Ingo H. de Boer)<br />
<br />
Also cvsgrab support the following option to access a particular branch:<br />
<br />
-tag <version tag> [optional] The version tag of the files to download<br />
<br />
For example to get the latest 4.4 branch:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xxx<br />
-tag release-4-4<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# 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.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
http://www.google.com/url?sa=D&q=http%3A%2F%2Fpublic.kitware.com%2Fpipermail%2Fvtkusers%2F2003-October%2F070054.html<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# 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''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
For a more elaborate DICOM library that supports compressed jpeg, you might try [http://www.creatis.insa-lyon.fr/Public/Gdcm/ Gdcm].<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
1) Using ReleaseDataFlag<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
2) Use ImmediateModeRendering<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
3) Use triangle strips via vtkStripper.<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
4) Use a different filter or mapper<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use STL. However, the following policy<br />
applies.<br />
<br />
# 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.<br />
# 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.<br />
# Include the VTK wrapper header files: vtkstd/map instead of map.<br />
# Use the vtkstd:: namespace to refer to STL classes and functions.<br />
<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| MPEG2 || || vtkMPEG2Writer<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows and Mac workstations.<br />
<br />
=== What Graphics Cards work with VTK ===<br />
<br />
VTK uses OpenGL to perform almost all of its rendering and some graphics cards/drivers have better support for OpenGL than others. This is not a listing of what cards perform well. It is a listing of what cards actually produce correct results. Here is a list of cards and their status roughly in best to worst order.<br />
<br />
* Any Nvidia desktop card on Windows -- 100% compatible<br /> <br />
* Any ATI desktop cards on Windows -- 100% compatible<br /><br />
* Mesa -- most releases pass all VTK tests<br /><br />
* Microsoft Software OpenGL -- passes all VTK tests but does have a couple bugs<br /><br />
* Mac graphics cards -- these usually pass all VTK tests. Older cards may have some issues, for example, the ATI Rage 128 Pro does not support textures larger than 1024x1024.<br /><br />
* Non-linux UNIX cards (Sun HP SGI) -- These generally work<br /><br />
* Any Nvidia card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Any ATI card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Nvidia laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests<br /><br />
* ATI laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests (e.g. [http://public.kitware.com/pipermail/vtkusers/2004-August/075966.html ATI Mobility Radeon 9600])<br /><br />
* Intel Extreme Graphics -- fails some VTK tests<br /><br />
<br />
=== How do I build the examples on the PC running Windows? ===<br />
<br />
Since building the C++ examples on the PC isn't all that easy, here are<br />
some instructions from Jack McInerney.<br />
<br />
Steps for creating a VTK C++ project 8/14/96<br />
<br />
This is based on what I learned creating a project to run the Mace<br />
example. These steps allowed me to successfully built and run this example.<br />
<br />
# Create a console project (File, New, then select Console application).<br />
# Add the files of interest to the project. (e.g., Mace.cxx)<br />
# Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies<br /> 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<br />
# 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).<br />
# 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 <br /> This is a self extracting archive which contains these files. Simply place them in your windows system directory.<br />
# Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless<br /><br />
<br />
When you go to run the program, it will bomb out unless it can find 2<br />
DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the<br />
project directory or the C:\WINDOWS directory. These files are supplied<br />
on the vtk CD-ROM (in the vtk\bin directory).<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
vtk builds on 64 bit systems, that is, systems where sizeof(void*) is 64 bits. However, parts of the vtk codebase are not 64 bit clean and so runtime problems are likely if that code is used.<br />
<br />
===== General =====<br />
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.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work reasonably with 64 bit Cocoa.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== What size swap space should I use on a PC? ===<br />
<br />
Building vtk on the PC requires a significant amount of memory (at least<br />
when using Visual C++)... but the final product is nice and compact. To<br />
build vtk on the PC, we recommend setting the min/max swap space to at<br />
least 400MB/500MB (depending on how much RAM you have... the sum of RAM<br />
and swap space should be roughly 500+ MB).<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
Struggled a few hours to get VTK to do offscreen rendering. I use it to<br />
batch process medical images. Without actually producing output on the<br />
screen, I still print resulting images in a report to easily review the<br />
results of an experiment.<br />
<br />
Here is how I solved this problem for VTK version 4.2.2.<br />
<br />
1. Download Mesa-4.0.4 source<br />
<br />
Modify Mesa-4.0.4/Make-config in the 'linux:' target the following vars:<br />
<br />
GL_LIB = libVTKMesaGL.so<br />
GLU_LIB = libVTKMesaGLU.so<br />
GLUT_LIB = libVTKMesaglut.so<br />
GLW_LIB = libVTKMesaGLw.so<br />
OSMESA_LIB = libOSVTKMesa.so<br />
<br />
In Mesa 6.2.1 you need to edit Mesa/configs/default instead:<br />
<br />
# Library names (base name)<br />
GL_LIB = VTKMesaGL<br />
GLU_LIB = VTKMesaGLU<br />
GLUT_LIB = VTKMesaglut<br />
GLW_LIB = VTKMesaGLw<br />
OSMESA_LIB = VTKMesaOSMesa<br />
<br />
<br />
And then export this env var:<br />
<br />
export 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"<br />
<br />
then<br />
<br />
For Mesa 4.0.4<br />
<br />
make -f Makefile.X11 linux <br />
cp Mesa-4.0.4/lib/* /data/usr/mesa404/lib/<br />
<br />
in Mesa 6.2.1:<br />
<br />
make linux-x86<br />
make install<br />
(I generally use /opt/VTKMesa/*)<br />
<br />
I use 'VTKMesa' name extension to avoid conflicts with my RH9.0 libs<br />
(especially OSMesa lib in XFree!). I'm using shared libraries, because<br />
that allows me to use dynamic libs from VTK and not the vtk program<br />
itself without explicitly having to load VTKMesaGL with my app. I copied<br />
the 'VTKMesa' libs in /data/usr/mesa404/lib/, but any odd place probably<br />
will work. Avoid /usr/lib /usr/local/lib for now.<br />
<br />
2. Follow normal instructions to get a proper working vtk, then<br />
<br />
ccmake <br />
<br />
with the following options:<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
| VTK_USE_MANGLED_MESA || ON<br />
|-<br />
| MANGLED_MESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_MESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaGL.so<br />
|-<br />
| MANGLED_OSMESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_OSMESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaOSMesa.so<br />
|-<br />
| OPENGL_xmesa_INCLUDE_DIR || /data/usr/mesa404/include<br />
|}<br />
<br />
test using /data/prog/VTK-4.2.2/Examples/MangledMesa/Tcl scripts<br />
<br />
<br />
If you're doing things on UNIX, you should also look at [[VTK Classes]]. It has links to RenderWindow objects that are probably easier to use than rebuilding VTK with Mesa.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
On Mac OS X, there are (at least) two kinds of executables:<br />
* [http://developer.apple.com/documentation/MacOSX/Conceptual/BPInternational/Articles/InternatSupport.html#//apple_ref/doc/uid/20000278-73764 Application Bundles]<br />
* plain UNIX executables<br />
<br />
For a program to be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction) it really should be an Application Bundle. If a plain UNIX executable tries, there will be various bugs, such as keyboard and mouse events not working reliably.<br />
<br />
Many, but not all, of the example VTK applications are built as plain UNIX executables, and thus have these problems. This is [http://www.vtk.org/Bug/bug.php?op=show&bugid=2025 VTK bug 2025].<br />
<br />
When you build your own VTK application, it is best to make it in the form of an Application Bundle. With CMake 2.0.5 or later, simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an Application Bundle (perhaps because your app needs command line parameters) you might be able to avoid the above problems by adding an [http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/ConfigFiles.html#//apple_ref/doc/uid/20002091-SW1 __info_plist section] to your Mach-O executable. If you succeed, please post to the VTK list.<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.3 and older, the short answer is "no".<br />
<br />
For VTK CVS the short answer is "mostly". You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. The usual settings are:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk <br />
<br />
This will result in a Universal build. However, there may be runtime bugs due to VTK's use of TRY_RUN. Work is being done to improve this situation.<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
=== How can a user process access more than 2 GB of ram in 32-bit Windows? ===<br />
<br />
By default on Windows, the most memory that a user process can access is 2 GB, no matter how much RAM you have installed in your system. With Windows XP Professional you can make it possible for a process to use up to 3 GB of memory by doing two things:<br />
<br />
1) Modify the boot parameters in boot.ini (on my 32 bit WinXP Pro machine, it's in: "C:\boot.ini") to tell the operating system that you want user processes to have access to up to 3GB of RAM (This is a really important file, and if you don't know what you are doing, stop reading this and go back to work!). This is done by adding the /3GB flag to the line of the file that tells the boot loader where the operating system is. My boot.ini file looks like:<br />
<br />
[boot loader]<br />
timeout=30<br />
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS<br />
[operating systems]<br />
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /3GB<br />
<br />
This is a very bad file to make mistakes on, so don't - it may be very difficult to repair your computer to boot if you mess up this file. There is a nice description of this in the Microsoft article <br />
[http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx Memory Support and Windows Operating Systems].<br />
<br />
2) The other thing that you need to do is make your executable LARGEADDRESSAWARE. Assuming that you have a Windows binary that you want to try this on, you can use the 'editbin' utility that comes with Visual Studio to change the setting of one bit (the IMAGE_FILE_LARGE_ADDRESS_AWARE bit) in the image header of the executable. For a program 'prog.exe' you can make the change by<br />
<br />
editbin /LARGEADDRESSAWARE prog.exe<br />
<br />
Of course, depending on how your program handles memory you might find that it crashes when you try to use the extra memory, but that's a separate issue. If you are compiling your program with a version of Visual Studio you should be able to find the switch to make your program /LARGEADDRESSAWARE.<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes in VTK between 3.2 and 4.0 ===<br />
<br />
* 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.<br />
<br />
* 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<br />
<br />
* Added special methods to data arrays to replace methods like<br />
<br />
tc SetTCoord i x y 0<br />
<br />
or<br />
<br />
vc SetVector i vx vy vz<br />
<br />
in interpreted languages (Tcl, Python, Java). Use:<br />
<br />
tc SetTuple2 i x y<br />
<br />
or<br />
<br />
vc SetTuple3 i vx vy vz<br />
<br />
* 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.<br />
<br />
* vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.<br />
<br />
* 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.<br />
<br />
* 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).<br />
<br />
* The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.<br />
<br />
* Support for reading and writing PGM and JPEG images has been included.<br />
<br />
* 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.<br />
<br />
* 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 Imaging 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.<br />
<br />
* 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.<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* 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.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* 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.<br />
<br />
* 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:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== How do I upgrade my existing C++ code from 3.2 to 4.x? ===<br />
<br />
This is (a corrected version of) an email that was posted to vtkusers.<br />
Please feel free to correct or add anything.<br />
<br />
{| cellspacing="3" <br />
|- valign="top"<br />
|width="55%" bgcolor="#f0f0ff" style="border:1px solid #ffc9c9;padding:1em;padding-top:0.5em;"|<br />
<br />
I've just ported my medium-sized (40K lines) application from vtk3.2 to<br />
vtk4.x. I thought I would share my experiences with you, in case there<br />
were people out there contemplating it but a bit scared.<br />
<br />
One source of information for upgrading code is:<br />
<br />
http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the<br />
script in the zip file.<br />
<br />
So,<br />
<br />
I switched all my include directories to the new VTK ones and<br />
recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and<br />
vtkTCoords which have both been removed. Where I was using single value<br />
scalars, like this:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetNumberOfScalars(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetScalar(i,2.3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *scalars = vtkFloatArray::New();<br />
scalars->SetNumberOfComponents(1);<br />
scalars->SetNumberOfTuples(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetTuple1(i,2.3);<br />
...<br />
<br />
OK so far, far fewer errors.<br />
<br />
Where I had 2D texture coordinates:<br />
<br />
vtkTCoords *tcoords = vtkTCoords::New();<br />
tcoords->SetNumberOfTCoords(N);<br />
...<br />
float p[3];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTCoord(i,p);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *tcoords = vtkFloatArray::New();<br />
tcoords->SetNumberOfComponents(2);<br />
tcoords->SetNumberOfTuples(N);<br />
...<br />
float p[2];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTuple(i,p);<br />
....<br />
<br />
All well and good, still fewer errors. Make sure you call<br />
SetNumberOfComponents *before* SetNumberOfTuples else you'll get<br />
problems (I did!).<br />
<br />
Where I was creating 0-255 image data and had been using:<br />
<br />
vtkScalars* scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
...<br />
<br />
Going well!<br />
<br />
When creating RGB images, I had been using:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfScalars(X*Y);<br />
...<br />
scalars->SetActiveComponent(0);<br />
scalars->SetScalar(i,val1);<br />
scalars->SetActiveComponent(1);<br />
scalars->SetScalar(i,val2);<br />
scalars->SetActiveComponent(2);<br />
scalars->SetScalar(i,val3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfTuples(X*Y);<br />
...<br />
scalars->SetComponent(i,0,val1);<br />
scalars->SetComponent(i,1,val2);<br />
scalars->SetComponent(i,2,val3);<br />
...<br />
<br />
My remaining errors concerned vtkWin32OffscreenRenderWindow that has<br />
been removed. Where I had been using:<br />
<br />
vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New();<br />
offscreen->SetOffScreenRendering(1);<br />
...<br />
<br />
All done. I'd had to throw in some #include "vtkFloatArray.h" and things<br />
like that of course. Zero compile errors.<br />
<br />
Had to remember to link against the new vtk lib files, so I removed<br />
<br />
vtkdll.lib <br />
<br />
and added<br />
<br />
vtkCommon.lib<br />
vtkGraphics.lib<br />
<br />
etc.<br />
<br />
Zero link errors. My program is up and running again, no apparant<br />
problems. Plus now I can use all the new features of vtk4. (And I'm sure<br />
it's faster but maybe that's my imagination.)<br />
<br />
All this took me about three hours.<br />
<br />
Bye!<br />
<br />
Tim.<br />
|}<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was releaseed in February 2003. VTK 4.4 (which is an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, and 5.0.3 in March 2007.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# 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.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* 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.<br />
#* 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.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* 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.<br />
* 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).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* 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. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* 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.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
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.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== Using Volume Rendering in VTK ===<br />
<br />
I recently updated my VTK CVS version. And my c++ code that use to work fine are now complaining about:<br />
<br />
undefined reference to `vtkUnstructuredGridAlgorithm::SetInput(vtkDataObject*)'<br />
undefined reference to `vtkUnstructuredGridAlgorithm::GetOutput()' <br />
<br />
There is now a new subfolder and a new option to enable building the VolumeRendering library. You have to turn VTK_USE_VOLUMERENDERING to ON in order to use it. Also make sure that your executable is linking properly to this new library:<br />
<br />
ADD_EXECUTABLE(foo foo.cxx)<br />
TARGET_LINK_LIBRARIES(foo vtkVolumeRendering)<br />
<br />
== OpenGL requirements ==<br />
<br />
=== Terminology ===<br />
<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
<br />
==== Linux/Unix ====<br />
<br />
Two ways:<br />
<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
<br />
* vendor specific tool<br />
<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or<br />
hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
== Miscellaneous questions ==<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. We think it's pretty reasonable. We do restrict the<br />
distribution of modified code. This is primarily a revision control<br />
issue. We don't want a bunch of renegade vtks running around without us<br />
having some idea why the changes were made and giving us a chance to<br />
incorporate them into the general release.<br />
<br />
The text of the VTK copyright is available [http://www.vtk.org/copyright.php here].<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
=== What is the deal with the patents ===<br />
<br />
As the copyright mentions there are some patents used in VTK. If you use<br />
any code in the Patented/ directory for commercial application you<br />
should contact the patent holder and obtain a license.<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by General Electric Company: vtkDecimate, vtkMarchingCubes,<br />
vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface.<br />
The GE contact is:<br />
<br />
Carl B. Horton<br />
Sr. Counsel, Intellectual Property<br />
3000 N. Grandview Blvd., W-710<br />
Waukesha, WI 53188<br />
Phone: (262) 513-4022<br />
E-Mail: mailto:Carl.Horton@med.ge.com<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by Kitware, Inc.: vtkGridSynchronizedTemplates3D,<br />
vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and<br />
vtkSynchronizedTemplates3D. The Kitware contact is:<br />
<br />
Ken Martin<br />
Kitware<br />
28 Corporate Drive, Suite 204,<br />
Clifton Park, NY 12065<br />
Phone:1-518-371-3971<br />
E-Mail: mailto:kitware@kitware.com<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=11354CMake FAQ2008-01-17T23:25:20Z<p>Seanmcbride: /* How do I build universal binaries on Mac OS X? */</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent and compiler-independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. CMake is quite sophisticated: it is possible to support complex environments requiring system configuration, preprocessor generation, code generation, and template instantiation. Please go to http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== CMake roadmap and release schedule ===<br />
CMake 2.4 is out. The bug tracker at http://www.cmake.org/Bug also has a number of feature requests for CMake. These feature requests typically et rolled into future versions of CMake.<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
The [http://www.kitware.com/products/cmakebook.html Mastering CMake] version 2.2 book thoroughly covers CMake 2.2.3 and earlier. Since the printing of the book CMake 2.4 has been released but the book is by no means out of date.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
Set CMAKE_VERBOSE_MAKEFILE to ON. This will make generator to produce all outputs, including compiler lines.<br />
<br />
If you are on Windows using Borland or NMake Makefiles, then you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to "".<br />
<br />
On Makefile generators, there is a shortcut by setting Makefile variable VERBOSE to 1. For example on UNIX:<br />
<br />
make VERBOSE=1<br />
<br />
and Windows:<br />
nmake /S force silent mode, overrides (CMAKE_VERBOSE_MAKFILE)<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink it by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
CMake build settings are stored in the CMake cache corresponding to a project's build tree. They are called CMake "cache entries" and have no relation to your command shell's environment variables. Use a CMake GUI (CMakeSetup on Windows or ccmake on UNIX) or the wizard mode (cmake -i) to edit cache entries. Initial values may also be specified for a build by using the -D command line argument to cmake when it is first run to produce a new build tree.<br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy. In order to choose a different compiler create a new build tree and set the CC and CXX environment variables to the compiler you want before running CMake.<br />
<br />
NOTE: While I don't know what the preferred method of doing it is, I do know that the advice above (to set CC and CXX env vars) is in direct conflict with advice somewhere else that says not to use env vars to control CMAKE... Hopefully someone that knows a little more than I will fix this discrepancy.<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
Since CMake 1.6, you can use tab completion in the path entries in CCMake. All you do is type first couple of characters and press <TAB> key. CCMake will examine the current typed path and try to expand it to some existing path. If that is possible, it will do it. If not, it will not do anything.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
This means that there is a CMakeCache.txt file in the source tree, possibly as part of an existing in-source build. If CMake is given the path to a directory with a CMakeCache.txt file, it assumes the directory is a build tree. Therefore if one runs "cmake ../mysrc" to build out-of-source but there is a mysrc/CMakeCache.txt file then cmake will treat mysrc as the build tree.<br />
<br />
This is a side-effect of the feature that allows "cmake ." to be used to regenerate a build tree. The behavior will not be changed because mixing in-source and out-of-source builds is not safe anyway (configured headers may be found in the wrong place).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be built into executables so they can find shared libraries at run time. If the build tree is moved old executables may use the old shared libraries, and not the new ones.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
The short answer is NO. The reason is because full paths are used in CMake, see above. The main problem is that cmake would need to detect when the binary tree has been moved and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking exactly which files are generated as part of running CMake. Providing a distclean target would give users the false impression that it would work as expected. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
A "make distclean" target is only necessary if the user performs an in-source build. CMake supports in-source builds, but we strongly encourage users to adopt the notion of an out-of-source build. Using a build tree that is separate from the source tree will prevent CMake from generating any files in the source tree. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the developer can specify a list of files to be deleted. This can be done using SET_DIRECTORY_PROPERTIES setting property ADDITIONAL_MAKE_CLEAN_FILES to the list of files.<br />
<br />
We however strongly recommend using an "out-of-source" build which never writes any files to the source tree. Using a separate source and build tree greatly reduces the need for "make clean" and "make distclean" targets to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
CMake by default maintains quite a bit of backwards compatibility to support older projects that used earlier versions of CMake. This backwards compatibility comes at the expense of allowing new CMakeLists.txt to use deprecated features and still work. To deal with this problem, CMake always creates a cache entry called CMAKE_BACKWARDS_COMPATIBILITY and sets it to the version (major.minor) of CMake currently running. During the "Configure" step, CMake will support enough backward compatibility features to simulate the version of CMake specified by this cache entry's value. When a new version of CMake is run on an old project and reports errors, one can set CMAKE_BACKWARDS_COMPATIBILITY to an older version of CMake to solve the problem.<br />
<br />
A good practice for project developers that use CMake is to add code like this to the RELEASE version of the source tree:<br />
<br />
IF(CMAKE_BACKWARDS_COMPATIBILITY GREATER 2.0)<br />
SET(CMAKE_BACKWARDS_COMPATIBILITY 2.0 CACHE STRING<br />
"Latest version of CMake when this project was released." FORCE)<br />
ENDIF(CMAKE_BACKWARDS_COMPATIBILITY GREATER 2.0)<br />
<br />
That way whenever someone tries to build the release with a later version of CMake, the necessary backward compatibility level will already be set. DO NOT keep this code in the development version of the source tree. When a new version of CMake is released, it is good practice to fix the problems it reports in the source tree instead of abusing the backward compatibility features.<br />
<br />
When a new version of CMake is released that adds some features, it is nice to be able to take advantage of them in your project. However, doing so will cause other developers that have not yet upgraded to the new CMake to get errors when attempting to build the source. In order to have CMake tell them that they need to upgrade, your project should contain a line like this:<br />
<br />
CMAKE_MINIMUM_REQUIRED(VERSION 2.0)<br />
<br />
at the top of your main CMakeLists.txt file. This will tell older versions of CMake that they are too old to build this project and produce a message telling the user they need to upgrade to a more recent version of CMake.<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
The cache variables listed in the GUI when you press "Configure" are used to initialize the values seen by the code in CMakeLists.txt files.<br />
<br />
Changes made by the code are used during the configure step and seen by the generators but are not stored back into the cache. For example:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
will turn on building of shared libraries for the directory containing the command and all subdirectories, but the change will not appear in the GUI.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeList.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
You must use GET_TARGET_PROPERTY to obtain the location of the generated executable. Some platforms put executables in separate directories according to their build type, i.e. MSVC typically has subdirectories for "Debug" and "Release" builds. For the DEPENDS part of the command, you can either use DOIT_EXE or just simply use the name of the target. This will ensure that the target doit is built before any target that uses the output from the custom command.<br />
<br />
ADD_EXECUTABLE(doit ${DOIT_SOURCE_FILES})<br />
GET_TARGET_PROPERTY(DOIT_EXE doit LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${DOIT_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS doit<br />
)<br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the generator command is another executable built in the same project:<br />
<br />
ADD_EXECUTABLE(my_generator my_generator.c)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/generated.c<br />
COMMAND ${MY_GENERATOR_EXE} ${CMAKE_CURRENT_BINARY_DIR}/generated.c ${CMAKE_CURRENT_SOURCE_DIR}/some_input.txt<br />
DEPENDS my_generator ${CMAKE_CURRENT_SOURCE_DIR}/some_input.txt<br />
)<br />
ADD_EXECUTABLE(generated generated.c)<br />
<br />
For this example, we assumed that the my_generator program accepts as its first argument the full path to the source file to generate, and the second argument is input for the generator. When either the generator source or the sample input changes, the generated.c source will be regenerated.<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. For example, suppose you had a program that read input.txt and generated three files output1.cpp, output2.h, and output3.cpp, and that those three files needed to be compiled into an executable program. The cmake list file for that would look like this:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
An unfortunate holdover from ancient CMake versions is that certain commands are "inherited" into subdirectories and others are not. EXEC_PROGRAM is not inherited. What this means is that when the listfile code from a parent directory executes in a subdirectory the EXEC_PROGRAM command is left out. Therefore the code executes differently. This problem was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
This will store the result in a global location so it will be available in the subdirectory. Be sure to choose a descriptive name for MY_OUTPUT to avoid conflict in the global setting.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
You may need \\ instead of \ due to CMake argument processing. \" works fine in SET statements, but you may need \\\" in some CMake functions. It can get hairy. This section needs elaboration.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This makes the script kind of hard to follow, for example:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
If you find this too confusing you can enable the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option which will allow you to use a slightly more conventional syntax where the ELSE() and ENDIF() constructs can be empty:<br />
<br />
SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSEIF(APPLE)<br />
...do something else...<br />
ELSE()<br />
...do something else...<br />
ENDIF()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: this will only work with gcc (since the flags would need to be<br />
declined with the possible compilers). Additionaly this will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt...<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?rev=1.12&root=CMake&view=markup]<br />
file located in the CVS repository. <br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
Use the following approach. Note that you have to set LATEX_COMPILE to LaTeX executable, DVIPDF_COMPILE to dvi to pdf converter. Also, the LaTeX source is TDocument.tex and the result is called TDocument.pdf. Note that this uses commands in CMake version 1.8 or later.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, then this is necessary on some platforms but not others. The decision was made to make this consistent across all platforms and library types for simplicity and reliability.<br />
<br />
We have never seen a real case when this causes a problem. The most commonly suggested example is when A is a static library then both B and C get copies of it. On most platforms this is already an error because it is not safe to link static libraries into shared libraries: there is no way to ensure that the static libraries contain relocatable objects (built with -fPIC or equivalent flag).<br />
<br />
In the future CMake may distinguish between the linking interface (what libraries are needed for C to use library B) and the linking implementation (what libraries are needed to create B in the first place). This has not yet been implemented.<br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake has a limited support for scanning dependencies. Currently it does not support:<br />
* Preprocessor macro<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
* Fixed form comment (fortran 77/90/95)<br />
C USE bla<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
Yes, when a makefile generator is used. After the build completes, one may run "make install" to install any files the project configured to be installed. Running<br />
<br />
make install DESTDIR="/home/me/mydist"<br />
<br />
will cause the installation to copy files to "/home/me/mydist/${CMAKE_INSTALL_PREFIX}/...". This is useful for package maintainers.<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used to create a Universal Binary.<br />
<br />
Universal Binaries are essentially cross compilation and so you should avoid using TRY_RUN, especially for things like testing endianess or variable size because the result will only be correct for one architecture.<br />
<br />
Lastly, note that CTest is only able to test one architecture. See bug 6157.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
Using ADD_CUSTOM_COMMAND. For example, let's say you are creating executable MyExecutable, which needs the resources file Carbon.r. All you do is add a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
Your program is a GUI application using WinMain (/subsystem:windows) and not a console application using main. You have to use the WIN32 option with the ADD_EXECUTABLE command.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
This can be set in a CMakeLists.txt file and will enable MFC in the application. It should be set to 1 or 2. This is used in visual studio 6 and 7 project files. The CMakeSetup dialog uses MFC and the CMakeLists.txt looks like this:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
Defines a group into which sources will be placed in project files. This is mainly used to setup file tabs in Visual Studio. Any file whose name is listed or matches the regular expression will be placed in this group provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event a file matches multiple groups, the LAST group that explicitly lists the file will be favored, if any. If no group explicitly lists the file, the LAST group whose regular expression matches the file will be favored. For backwards compatibility this command is also supports the format SOURCE_GROUP(name regex).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
For Visual Studio.NET (version 7.0 and above) it is possible to set the CMAKE_CONFIGURATION_TYPES variable to the build type(s) (Debug/Release/...) that you want. This does not work for Visual Studio 6. There is however a way to achieve this. To create your own set of configurations:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- You MUST remove the targets that you do not want in your set at the bottom of the file (e.g. '# Name "OUTPUT_LIBNAME - Win32 MinSizeRel"')<br />
- You can remove the '!IF "$(CFG)" == ...' until '!ELSEIF "$(CFG)" == ...' or '!ELSEIF "$(CFG)" == ...' until '!ENDIF' lines for the configurations you do not want. Make sure that the resulting code still starts with '!IF ...' and ends with '!ENDIF' with any number of '!ELSEIF' sections in between. If you create templates for a single configuration (aka makefile), it is possible to remove everything starting from '!IF' until and including '!ENDIF' and leave only the contents of the relevant section intact.<br />
- Do not edit the lines starting with '!MESSAGE' as the changes may - and probably will - corrupt your resulting DSP files. The only thing I was able to change without corrupting the DSP is to remove the irrevant configurations from the "Possible choices for configuration are:" list.<br />
<br />
If you have only a single configuration in your set, you may want to get rid of the intermediate dir that MsDev creates. You can do that by setting:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
Additionally you should then also edit the '# ADD LINK32' line in the DLLHeader.dsptemplate file. Change for example '/out:"LIBRARY_OUTPUT_PATHDebug/OUTPUT_LIBNAMEDEBUG_POSTFIX.dll"' into '/out:"LIBRARY_OUTPUT_PATHOUTPUT_LIBNAMEDEBUG_POSTFIX.dll"' (Note that the configuration name and also the slash are removed).<br />
<br />
It is even possible to rename the pre-defined configurations of CMake in this way. Let's say you prefer 'PreProduction' over 'RelWithDebInfo'. You can change the name in the *.dsptemplate files, but you should also change it in the CMakeVisualStudio6Configurations.cmake file. Be careful, however. Only entries relevant to the configuration name should be changed. Do not change the /debug options and the entries that contain the build type in capital characters. Internally in CMake the build type will still remain 'RelWithDebInfo', so also the CMAKE_BUILD_TYPE should be set to the old value. You can only change the way it is named in MSDev.<br />
<br />
Note: Apparently MsDev as command-line build tool only performs a partial check on the build type. It will match all configuration types that CONTAIN the build type in their name. (e.g. if you have renamed RelWithDebInfo to DebugRelease, Debug will build Debug and DebugRelease, Release will build Release and DebugRelease. This may be exactly what you want, but be warned.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
{{CMake/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=11349CMake FAQ2008-01-16T15:13:48Z<p>Seanmcbride: /* How do I build universal binaries on Mac OS X? */</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent and compiler-independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. CMake is quite sophisticated: it is possible to support complex environments requiring system configuration, preprocessor generation, code generation, and template instantiation. Please go to http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== CMake roadmap and release schedule ===<br />
CMake 2.4 is out. The bug tracker at http://www.cmake.org/Bug also has a number of feature requests for CMake. These feature requests typically et rolled into future versions of CMake.<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
The [http://www.kitware.com/products/cmakebook.html Mastering CMake] version 2.2 book thoroughly covers CMake 2.2.3 and earlier. Since the printing of the book CMake 2.4 has been released but the book is by no means out of date.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
Set CMAKE_VERBOSE_MAKEFILE to ON. This will make generator to produce all outputs, including compiler lines.<br />
<br />
If you are on Windows using Borland or NMake Makefiles, then you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to "".<br />
<br />
On Makefile generators, there is a shortcut by setting Makefile variable VERBOSE to 1. For example on UNIX:<br />
<br />
make VERBOSE=1<br />
<br />
and Windows:<br />
nmake /S force silent mode, overrides (CMAKE_VERBOSE_MAKFILE)<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink it by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
CMake build settings are stored in the CMake cache corresponding to a project's build tree. They are called CMake "cache entries" and have no relation to your command shell's environment variables. Use a CMake GUI (CMakeSetup on Windows or ccmake on UNIX) or the wizard mode (cmake -i) to edit cache entries. Initial values may also be specified for a build by using the -D command line argument to cmake when it is first run to produce a new build tree.<br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy. In order to choose a different compiler create a new build tree and set the CC and CXX environment variables to the compiler you want before running CMake.<br />
<br />
NOTE: While I don't know what the preferred method of doing it is, I do know that the advice above (to set CC and CXX env vars) is in direct conflict with advice somewhere else that says not to use env vars to control CMAKE... Hopefully someone that knows a little more than I will fix this discrepancy.<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
Since CMake 1.6, you can use tab completion in the path entries in CCMake. All you do is type first couple of characters and press <TAB> key. CCMake will examine the current typed path and try to expand it to some existing path. If that is possible, it will do it. If not, it will not do anything.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
This means that there is a CMakeCache.txt file in the source tree, possibly as part of an existing in-source build. If CMake is given the path to a directory with a CMakeCache.txt file, it assumes the directory is a build tree. Therefore if one runs "cmake ../mysrc" to build out-of-source but there is a mysrc/CMakeCache.txt file then cmake will treat mysrc as the build tree.<br />
<br />
This is a side-effect of the feature that allows "cmake ." to be used to regenerate a build tree. The behavior will not be changed because mixing in-source and out-of-source builds is not safe anyway (configured headers may be found in the wrong place).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be built into executables so they can find shared libraries at run time. If the build tree is moved old executables may use the old shared libraries, and not the new ones.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
The short answer is NO. The reason is because full paths are used in CMake, see above. The main problem is that cmake would need to detect when the binary tree has been moved and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking exactly which files are generated as part of running CMake. Providing a distclean target would give users the false impression that it would work as expected. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
A "make distclean" target is only necessary if the user performs an in-source build. CMake supports in-source builds, but we strongly encourage users to adopt the notion of an out-of-source build. Using a build tree that is separate from the source tree will prevent CMake from generating any files in the source tree. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the developer can specify a list of files to be deleted. This can be done using SET_DIRECTORY_PROPERTIES setting property ADDITIONAL_MAKE_CLEAN_FILES to the list of files.<br />
<br />
We however strongly recommend using an "out-of-source" build which never writes any files to the source tree. Using a separate source and build tree greatly reduces the need for "make clean" and "make distclean" targets to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
CMake by default maintains quite a bit of backwards compatibility to support older projects that used earlier versions of CMake. This backwards compatibility comes at the expense of allowing new CMakeLists.txt to use deprecated features and still work. To deal with this problem, CMake always creates a cache entry called CMAKE_BACKWARDS_COMPATIBILITY and sets it to the version (major.minor) of CMake currently running. During the "Configure" step, CMake will support enough backward compatibility features to simulate the version of CMake specified by this cache entry's value. When a new version of CMake is run on an old project and reports errors, one can set CMAKE_BACKWARDS_COMPATIBILITY to an older version of CMake to solve the problem.<br />
<br />
A good practice for project developers that use CMake is to add code like this to the RELEASE version of the source tree:<br />
<br />
IF(CMAKE_BACKWARDS_COMPATIBILITY GREATER 2.0)<br />
SET(CMAKE_BACKWARDS_COMPATIBILITY 2.0 CACHE STRING<br />
"Latest version of CMake when this project was released." FORCE)<br />
ENDIF(CMAKE_BACKWARDS_COMPATIBILITY GREATER 2.0)<br />
<br />
That way whenever someone tries to build the release with a later version of CMake, the necessary backward compatibility level will already be set. DO NOT keep this code in the development version of the source tree. When a new version of CMake is released, it is good practice to fix the problems it reports in the source tree instead of abusing the backward compatibility features.<br />
<br />
When a new version of CMake is released that adds some features, it is nice to be able to take advantage of them in your project. However, doing so will cause other developers that have not yet upgraded to the new CMake to get errors when attempting to build the source. In order to have CMake tell them that they need to upgrade, your project should contain a line like this:<br />
<br />
CMAKE_MINIMUM_REQUIRED(VERSION 2.0)<br />
<br />
at the top of your main CMakeLists.txt file. This will tell older versions of CMake that they are too old to build this project and produce a message telling the user they need to upgrade to a more recent version of CMake.<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
The cache variables listed in the GUI when you press "Configure" are used to initialize the values seen by the code in CMakeLists.txt files.<br />
<br />
Changes made by the code are used during the configure step and seen by the generators but are not stored back into the cache. For example:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
will turn on building of shared libraries for the directory containing the command and all subdirectories, but the change will not appear in the GUI.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeList.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
You must use GET_TARGET_PROPERTY to obtain the location of the generated executable. Some platforms put executables in separate directories according to their build type, i.e. MSVC typically has subdirectories for "Debug" and "Release" builds. For the DEPENDS part of the command, you can either use DOIT_EXE or just simply use the name of the target. This will ensure that the target doit is built before any target that uses the output from the custom command.<br />
<br />
ADD_EXECUTABLE(doit ${DOIT_SOURCE_FILES})<br />
GET_TARGET_PROPERTY(DOIT_EXE doit LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${DOIT_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS doit<br />
)<br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the generator command is another executable built in the same project:<br />
<br />
ADD_EXECUTABLE(my_generator my_generator.c)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/generated.c<br />
COMMAND ${MY_GENERATOR_EXE} ${CMAKE_CURRENT_BINARY_DIR}/generated.c ${CMAKE_CURRENT_SOURCE_DIR}/some_input.txt<br />
DEPENDS my_generator ${CMAKE_CURRENT_SOURCE_DIR}/some_input.txt<br />
)<br />
ADD_EXECUTABLE(generated generated.c)<br />
<br />
For this example, we assumed that the my_generator program accepts as its first argument the full path to the source file to generate, and the second argument is input for the generator. When either the generator source or the sample input changes, the generated.c source will be regenerated.<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. For example, suppose you had a program that read input.txt and generated three files output1.cpp, output2.h, and output3.cpp, and that those three files needed to be compiled into an executable program. The cmake list file for that would look like this:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
An unfortunate holdover from ancient CMake versions is that certain commands are "inherited" into subdirectories and others are not. EXEC_PROGRAM is not inherited. What this means is that when the listfile code from a parent directory executes in a subdirectory the EXEC_PROGRAM command is left out. Therefore the code executes differently. This problem was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
This will store the result in a global location so it will be available in the subdirectory. Be sure to choose a descriptive name for MY_OUTPUT to avoid conflict in the global setting.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
You may need \\ instead of \ due to CMake argument processing. \" works fine in SET statements, but you may need \\\" in some CMake functions. It can get hairy. This section needs elaboration.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This makes the script kind of hard to follow, for example:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
If you find this too confusing you can enable the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option which will allow you to use a slightly more conventional syntax where the ELSE() and ENDIF() constructs can be empty:<br />
<br />
SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSEIF(APPLE)<br />
...do something else...<br />
ELSE()<br />
...do something else...<br />
ENDIF()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: this will only work with gcc (since the flags would need to be<br />
declined with the possible compilers). Additionaly this will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt...<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?rev=1.12&root=CMake&view=markup]<br />
file located in the CVS repository. <br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
Use the following approach. Note that you have to set LATEX_COMPILE to LaTeX executable, DVIPDF_COMPILE to dvi to pdf converter. Also, the LaTeX source is TDocument.tex and the result is called TDocument.pdf. Note that this uses commands in CMake version 1.8 or later.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, then this is necessary on some platforms but not others. The decision was made to make this consistent across all platforms and library types for simplicity and reliability.<br />
<br />
We have never seen a real case when this causes a problem. The most commonly suggested example is when A is a static library then both B and C get copies of it. On most platforms this is already an error because it is not safe to link static libraries into shared libraries: there is no way to ensure that the static libraries contain relocatable objects (built with -fPIC or equivalent flag).<br />
<br />
In the future CMake may distinguish between the linking interface (what libraries are needed for C to use library B) and the linking implementation (what libraries are needed to create B in the first place). This has not yet been implemented.<br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake has a limited support for scanning dependencies. Currently it does not support:<br />
* Preprocessor macro<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
* Fixed form comment (fortran 77/90/95)<br />
C USE bla<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
Yes, when a makefile generator is used. After the build completes, one may run "make install" to install any files the project configured to be installed. Running<br />
<br />
make install DESTDIR="/home/me/mydist"<br />
<br />
will cause the installation to copy files to "/home/me/mydist/${CMAKE_INSTALL_PREFIX}/...". This is useful for package maintainers.<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for 32-bit PowerPC and Intel you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
If you wish to build both as 32 and 64 bit, do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386;ppc64;x86_64<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot (aka Mac OS SDK) to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake. The 10.4u SDK or later must be used.<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
Using ADD_CUSTOM_COMMAND. For example, let's say you are creating executable MyExecutable, which needs the resources file Carbon.r. All you do is add a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
Your program is a GUI application using WinMain (/subsystem:windows) and not a console application using main. You have to use the WIN32 option with the ADD_EXECUTABLE command.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
This can be set in a CMakeLists.txt file and will enable MFC in the application. It should be set to 1 or 2. This is used in visual studio 6 and 7 project files. The CMakeSetup dialog uses MFC and the CMakeLists.txt looks like this:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
Defines a group into which sources will be placed in project files. This is mainly used to setup file tabs in Visual Studio. Any file whose name is listed or matches the regular expression will be placed in this group provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event a file matches multiple groups, the LAST group that explicitly lists the file will be favored, if any. If no group explicitly lists the file, the LAST group whose regular expression matches the file will be favored. For backwards compatibility this command is also supports the format SOURCE_GROUP(name regex).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
For Visual Studio.NET (version 7.0 and above) it is possible to set the CMAKE_CONFIGURATION_TYPES variable to the build type(s) (Debug/Release/...) that you want. This does not work for Visual Studio 6. There is however a way to achieve this. To create your own set of configurations:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- You MUST remove the targets that you do not want in your set at the bottom of the file (e.g. '# Name "OUTPUT_LIBNAME - Win32 MinSizeRel"')<br />
- You can remove the '!IF "$(CFG)" == ...' until '!ELSEIF "$(CFG)" == ...' or '!ELSEIF "$(CFG)" == ...' until '!ENDIF' lines for the configurations you do not want. Make sure that the resulting code still starts with '!IF ...' and ends with '!ENDIF' with any number of '!ELSEIF' sections in between. If you create templates for a single configuration (aka makefile), it is possible to remove everything starting from '!IF' until and including '!ENDIF' and leave only the contents of the relevant section intact.<br />
- Do not edit the lines starting with '!MESSAGE' as the changes may - and probably will - corrupt your resulting DSP files. The only thing I was able to change without corrupting the DSP is to remove the irrevant configurations from the "Possible choices for configuration are:" list.<br />
<br />
If you have only a single configuration in your set, you may want to get rid of the intermediate dir that MsDev creates. You can do that by setting:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
Additionally you should then also edit the '# ADD LINK32' line in the DLLHeader.dsptemplate file. Change for example '/out:"LIBRARY_OUTPUT_PATHDebug/OUTPUT_LIBNAMEDEBUG_POSTFIX.dll"' into '/out:"LIBRARY_OUTPUT_PATHOUTPUT_LIBNAMEDEBUG_POSTFIX.dll"' (Note that the configuration name and also the slash are removed).<br />
<br />
It is even possible to rename the pre-defined configurations of CMake in this way. Let's say you prefer 'PreProduction' over 'RelWithDebInfo'. You can change the name in the *.dsptemplate files, but you should also change it in the CMakeVisualStudio6Configurations.cmake file. Be careful, however. Only entries relevant to the configuration name should be changed. Do not change the /debug options and the entries that contain the build type in capital characters. Internally in CMake the build type will still remain 'RelWithDebInfo', so also the CMAKE_BUILD_TYPE should be set to the old value. You can only change the way it is named in MSDev.<br />
<br />
Note: Apparently MsDev as command-line build tool only performs a partial check on the build type. It will match all configuration types that CONTAIN the build type in their name. (e.g. if you have renamed RelWithDebInfo to DebugRelease, Debug will build Debug and DebugRelease, Release will build Release and DebugRelease. This may be exactly what you want, but be warned.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
{{CMake/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=CMake_FAQ&diff=11348CMake FAQ2008-01-16T15:08:27Z<p>Seanmcbride: /* How can I apply resources on Mac OS X automatically? */</p>
<hr />
<div>== General information and availability ==<br />
=== What is CMake? ===<br />
CMake is a cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform-independent and compiler-independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. CMake is quite sophisticated: it is possible to support complex environments requiring system configuration, preprocessor generation, code generation, and template instantiation. Please go to http://www.cmake.org/HTML/About.html to learn more about CMake.<br />
<br />
=== What is the current release? ===<br />
The latest release of CMake is always available at: http://www.cmake.org/HTML/Download.html<br />
<br />
From there, you can fetch CMake binaries for Windows or several Unix variants, or you can download the source code of CMake.<br />
<br />
You can also access nightly development through CVS; see http://www.cmake.org/HTML/Download.html for more information. You may also browse the [http://www.cmake.org/cgi-bin/viewcvs.cgi/?root=CMake cvs repository online].<br />
<br />
=== CMake roadmap and release schedule ===<br />
CMake 2.4 is out. The bug tracker at http://www.cmake.org/Bug also has a number of feature requests for CMake. These feature requests typically et rolled into future versions of CMake.<br />
<br />
=== I found a Bug! What should I do? ===<br />
Please report the bug in our bug tracker: http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old bugs not to include duplicates, include detailed instructions of the bug and how to reproduce it.<br />
<br />
=== I want a new feature in CMake. What should I do? ===<br />
Report a feature request in our Bug tracker http://www.cmake.org/Bug<br />
<br />
Please make sure to look at the old feature requests not to include duplicates, include detailed instructions of the feature and proposed implementation.<br />
<br />
=== What is the most recent version covered by the Mastering CMake book? ===<br />
The [http://www.kitware.com/products/cmakebook.html Mastering CMake] version 2.2 book thoroughly covers CMake 2.2.3 and earlier. Since the printing of the book CMake 2.4 has been released but the book is by no means out of date.<br />
<br />
The following features have been added since printing the book:<br />
<br />
* New INSTALL command (cmake --help-command INSTALL)<br />
* New LIST command (cmake --help-command LIST)<br />
* Updated FIND_PATH, FIND_PROGRAM, and FIND_FILE commands to be more powerful (cmake --help-command FIND_PATH)<br />
* RPATH and Mac OS X install_name support (cmake --help-command SET_TARGET_PROPERTIES)<br />
* CPack Beta (not finished or documented)<br />
* EXECUTE_PROCESS was added and replaces EXEC_PROGRAM<br />
* Other changes have been bug fixes and internal CMake restructuring<br />
<br />
== Running CMake ==<br />
<br />
=== Is there an option to produce more 'verbose' compiling? ===<br />
Set CMAKE_VERBOSE_MAKEFILE to ON. This will make generator to produce all outputs, including compiler lines.<br />
<br />
If you are on Windows using Borland or NMake Makefiles, then you will see lines like:<br />
<br />
cl @c:\DOCUME~1\ANDY~1.KIT\LOCALS~1\Temp\nma03504<br />
<br />
The reason for this is that Borland and Microsoft Visual Studio make programs have limitation on the length of command strings. They overcome this limitation by writing arguments to the file and then pass file to the program.<br />
<br />
If you actually want to see what the command looks like, set CMAKE_START_TEMP_FILE and CMAKE_END_TEMP_FILE to "".<br />
<br />
On Makefile generators, there is a shortcut by setting Makefile variable VERBOSE to 1. For example on UNIX:<br />
<br />
make VERBOSE=1<br />
<br />
and Windows:<br />
nmake /S force silent mode, overrides (CMAKE_VERBOSE_MAKFILE)<br />
<br />
=== Is there a way to skip checking of dependent libraries when compiling? ===<br />
<br />
'''Using the Makefile Generator'''<br />
<br />
When using the Makefile generator under *nix you can append "/fast" to your target name. For example:<br />
<br />
make target_name/fast<br />
<br />
Under Windows use a backslash instead:<br />
<br />
make target_name\fast<br />
<br />
'''Using Visual Studio >= 7.1'''<br />
<br />
If you have Visual Studio .NET 7.1 or greater you can use the native option to right click on a project and choose to build just that project.<br />
<br />
'''Using Visual Studio <= 7.0'''<br />
<br />
CMake doesn't try to compile all dependent libraries when you compile a library but it will do so for binary targets. You can't avoid this however you can take advantage of CTRL+F7 to manually compile a source file for the affected target and then relink it by right clicking on it and choosing Link. You'll have to ensure that all dependent libraries are made up-to-date however or suffer through Visual's slow check.<br />
<br />
=== I set a cmake variable in my environment, but it didn't change anything. Why? ===<br />
CMake build settings are stored in the CMake cache corresponding to a project's build tree. They are called CMake "cache entries" and have no relation to your command shell's environment variables. Use a CMake GUI (CMakeSetup on Windows or ccmake on UNIX) or the wizard mode (cmake -i) to edit cache entries. Initial values may also be specified for a build by using the -D command line argument to cmake when it is first run to produce a new build tree.<br />
<br />
=== I change CMAKE_C_COMPILER in the GUI but it changes back on the next configure step. Why? ===<br />
Once a build tree is created with a given compiler it cannot be changed. There are a variety of implementation reasons for this policy. In order to choose a different compiler create a new build tree and set the CC and CXX environment variables to the compiler you want before running CMake.<br />
<br />
NOTE: While I don't know what the preferred method of doing it is, I do know that the advice above (to set CC and CXX env vars) is in direct conflict with advice somewhere else that says not to use env vars to control CMAKE... Hopefully someone that knows a little more than I will fix this discrepancy.<br />
<br />
=== In CCMake, typing full paths is tedious. Is there a better way? ===<br />
Since CMake 1.6, you can use tab completion in the path entries in CCMake. All you do is type first couple of characters and press <TAB> key. CCMake will examine the current typed path and try to expand it to some existing path. If that is possible, it will do it. If not, it will not do anything.<br />
<br />
For example:<br />
<br />
/usr/loc<TAB><br />
<br />
will expand to<br />
<br />
/usr/local/<br />
<br />
== Out-of-source build trees ==<br />
<br />
=== What is an "out-of-source" build? ===<br />
When your build generates files, they have to go somewhere. An in-source build puts them in your source tree. An out-of-source build puts them in a completely separate directory, so that your source tree is unchanged.<br />
<br />
In the first example, an in-place build is performed, i.e., the binaries are placed in the same directory as the source code.<br />
<br />
cd Hello<br />
ccmake .<br />
make<br />
<br />
In the second example, an out-of-place build is performed, i.e., the source code, libraries, and executables are produced in a directory separate from the source code directory(ies).<br />
<br />
mkdir HelloBuild<br />
cd HelloBuild<br />
ccmake ../Hello<br />
make<br />
<br />
Out-of-source builds are recommended, as you can build multiple variants in separate directories, e.g., HelloBuildDebug, HelloBuildRelease.<br />
<br />
Note: Before performing an out-of-source build ensure that any possible CMake generated in-source build information is removed from the source directory, e.g., CMakeFiles directory, and CMakeCache.txt.<br />
<br />
=== I run an out-of-source build but CMake generates in-source anyway. Why? ===<br />
This means that there is a CMakeCache.txt file in the source tree, possibly as part of an existing in-source build. If CMake is given the path to a directory with a CMakeCache.txt file, it assumes the directory is a build tree. Therefore if one runs "cmake ../mysrc" to build out-of-source but there is a mysrc/CMakeCache.txt file then cmake will treat mysrc as the build tree.<br />
<br />
This is a side-effect of the feature that allows "cmake ." to be used to regenerate a build tree. The behavior will not be changed because mixing in-source and out-of-source builds is not safe anyway (configured headers may be found in the wrong place).<br />
<br />
=== Why does CMake use full paths, or can I copy my build tree? ===<br />
CMake uses full paths because:<br />
<br />
# configured header files may have full paths in them, and moving those files without re-configuring would cause upredictable behavior.<br />
# because cmake supports out of source builds, if custom commands used relative paths to the source tree, they would not work when they are run in the build tree because the current directory would be incorrect.<br />
# on Unix systems rpaths might be built into executables so they can find shared libraries at run time. If the build tree is moved old executables may use the old shared libraries, and not the new ones.<br />
<br />
Can the build tree be copied or moved?<br />
<br />
The short answer is NO. The reason is because full paths are used in CMake, see above. The main problem is that cmake would need to detect when the binary tree has been moved and rerun. Often when people want to move a binary tree it is so that they can distribute it to other users who may not have cmake in which case this would not work even if cmake would detect the move.<br />
<br />
The workaround is to create a new build tree without copying or moving the old one.<br />
<br />
<br />
=== CMake does not generate a "make distclean" target. Why? ===<br />
Some build trees created with GNU autotools have a "make distclean" target that cleans the build and also removes Makefiles and other parts of the generated build system. CMake does not generate a "make distclean" target because CMakeLists.txt files can run scripts and arbitrary commands; CMake has no way of tracking exactly which files are generated as part of running CMake. Providing a distclean target would give users the false impression that it would work as expected. (CMake does generate a "make clean" target to remove files generated by the compiler and linker.)<br />
<br />
A "make distclean" target is only necessary if the user performs an in-source build. CMake supports in-source builds, but we strongly encourage users to adopt the notion of an out-of-source build. Using a build tree that is separate from the source tree will prevent CMake from generating any files in the source tree. Because CMake does not change the source tree, there is no need for a distclean target. One can start a fresh build by deleting the build tree or creating a separate build tree.<br />
<br />
(If a CMakeLists.txt uses ADD_CUSTOM_COMMAND to generate source files in the source tree, not the build tree, then in CMake 2.2 or higher "make clean" will remove them. See next question.)<br />
<br />
=== Running "make clean" does not remove custom command outputs. Why? ===<br />
In CMake 2.2 and higher custom command outputs should be removed by make clean. Make sure you are using at least this version. Prior to CMake 2.2 custom command outputs were not automatically added to the list of files to clean. In CMake 2.0 the developer can specify a list of files to be deleted. This can be done using SET_DIRECTORY_PROPERTIES setting property ADDITIONAL_MAKE_CLEAN_FILES to the list of files.<br />
<br />
We however strongly recommend using an "out-of-source" build which never writes any files to the source tree. Using a separate source and build tree greatly reduces the need for "make clean" and "make distclean" targets to clean away files that differ between builds.<br />
<br />
<br />
== Writing CMakeLists.txt ==<br />
<br />
=== How to have backward and forward compatibility? ===<br />
CMake by default maintains quite a bit of backwards compatibility to support older projects that used earlier versions of CMake. This backwards compatibility comes at the expense of allowing new CMakeLists.txt to use deprecated features and still work. To deal with this problem, CMake always creates a cache entry called CMAKE_BACKWARDS_COMPATIBILITY and sets it to the version (major.minor) of CMake currently running. During the "Configure" step, CMake will support enough backward compatibility features to simulate the version of CMake specified by this cache entry's value. When a new version of CMake is run on an old project and reports errors, one can set CMAKE_BACKWARDS_COMPATIBILITY to an older version of CMake to solve the problem.<br />
<br />
A good practice for project developers that use CMake is to add code like this to the RELEASE version of the source tree:<br />
<br />
IF(CMAKE_BACKWARDS_COMPATIBILITY GREATER 2.0)<br />
SET(CMAKE_BACKWARDS_COMPATIBILITY 2.0 CACHE STRING<br />
"Latest version of CMake when this project was released." FORCE)<br />
ENDIF(CMAKE_BACKWARDS_COMPATIBILITY GREATER 2.0)<br />
<br />
That way whenever someone tries to build the release with a later version of CMake, the necessary backward compatibility level will already be set. DO NOT keep this code in the development version of the source tree. When a new version of CMake is released, it is good practice to fix the problems it reports in the source tree instead of abusing the backward compatibility features.<br />
<br />
When a new version of CMake is released that adds some features, it is nice to be able to take advantage of them in your project. However, doing so will cause other developers that have not yet upgraded to the new CMake to get errors when attempting to build the source. In order to have CMake tell them that they need to upgrade, your project should contain a line like this:<br />
<br />
CMAKE_MINIMUM_REQUIRED(VERSION 2.0)<br />
<br />
at the top of your main CMakeLists.txt file. This will tell older versions of CMake that they are too old to build this project and produce a message telling the user they need to upgrade to a more recent version of CMake.<br />
<br />
=== How do I get the current source or binary directory? ===<br />
The variable CMAKE_CURRENT_SOURCE_DIR contains the absolute path to your current source directory, while CMAKE_CURRENT_BINARY_DIR points to the equivalent binary directory.<br />
<br />
=== Why are my CMake variables not updated in the GUI after a SET command? ===<br />
The cache variables listed in the GUI when you press "Configure" are used to initialize the values seen by the code in CMakeLists.txt files.<br />
<br />
Changes made by the code are used during the configure step and seen by the generators but are not stored back into the cache. For example:<br />
<br />
SET(BUILD_SHARED_LIBS ON)<br />
<br />
will turn on building of shared libraries for the directory containing the command and all subdirectories, but the change will not appear in the GUI.<br />
<br />
You can use the CACHE and FORCE options on the SET command to change variables in a way that will be reflected in the GUI. Run<br />
<br />
cmake --help-command SET<br />
<br />
to see full instructions for the command.<br />
<br />
<br />
=== How can I change the default build mode and see it reflected in the GUI? ===<br />
Adapt the following commands in your CMakeList.txt (this example sets the Release<br />
With Debug Information mode):<br />
<pre><br />
IF(NOT CMAKE_BUILD_TYPE)<br />
SET(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."<br />
FORCE)<br />
ENDIF(NOT CMAKE_BUILD_TYPE)<br />
</pre><br />
<br />
=== How do I generate an executable, then use the executable to generate a file? ===<br />
<br />
You must use GET_TARGET_PROPERTY to obtain the location of the generated executable. Some platforms put executables in separate directories according to their build type, i.e. MSVC typically has subdirectories for "Debug" and "Release" builds. For the DEPENDS part of the command, you can either use DOIT_EXE or just simply use the name of the target. This will ensure that the target doit is built before any target that uses the output from the custom command.<br />
<br />
ADD_EXECUTABLE(doit ${DOIT_SOURCE_FILES})<br />
GET_TARGET_PROPERTY(DOIT_EXE doit LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
COMMAND ${DOIT_EXE} ${CMAKE_CURRENT_SOURCE_DIR}/someinput.txt ${CMAKE_CURRENT_BINARY_DIR}/someoutput.txt<br />
DEPENDS doit<br />
)<br />
<br />
=== How can I generate a source file during the build? ===<br />
The ADD_CUSTOM_COMMAND command lets you generate a source file that you can then include in another target. For example:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
COMMAND ${CMAKE_COMMAND} copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.c ${CMAKE_CURRENT_BINARY_DIR}/foo.c<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.c<br />
)<br />
ADD_EXECUTABLE(foo foo.c)<br />
<br />
This will create an executable by copying bar.c to foo.c and then compiling foo.c to produce foo. CMake allows you to put generate source files in the current source or binary directory, so we were careful to output foo.c to the current binary directory. When we add foo.c to foo, CMake will look in either directory for it. Even if foo.c does not yet exist, CMake is smart enough to notice that a custom command creates it. (For the file named as the OUTPUT, CMake has its GENERATED source file property set to true.)<br />
<br />
You can also use ADD_CUSTOM_COMMAND when the generator command is another executable built in the same project:<br />
<br />
ADD_EXECUTABLE(my_generator my_generator.c)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/generated.c<br />
COMMAND ${MY_GENERATOR_EXE} ${CMAKE_CURRENT_BINARY_DIR}/generated.c ${CMAKE_CURRENT_SOURCE_DIR}/some_input.txt<br />
DEPENDS my_generator ${CMAKE_CURRENT_SOURCE_DIR}/some_input.txt<br />
)<br />
ADD_EXECUTABLE(generated generated.c)<br />
<br />
For this example, we assumed that the my_generator program accepts as its first argument the full path to the source file to generate, and the second argument is input for the generator. When either the generator source or the sample input changes, the generated.c source will be regenerated.<br />
<br />
Sometimes, the program doing the generation may generate multiple output files that each need to be part of the build. CMake 2.4 or higher supports having multiple files listed in the OUTPUT section. For example, suppose you had a program that read input.txt and generated three files output1.cpp, output2.h, and output3.cpp, and that those three files needed to be compiled into an executable program. The cmake list file for that would look like this:<br />
<br />
PROJECT(FOO)<br />
# make sure cmake addes the binary directory for the project to the include path<br />
INCLUDE_DIRECTORIES(${FOO_BINARY_DIR})<br />
# add the executable that will do the generation<br />
ADD_EXECUTABLE(my_generator my_generator.cxx)<br />
GET_TARGET_PROPERTY(MY_GENERATOR_EXE my_generator LOCATION)<br />
# add the custom command that will generate all three files<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${FOO_BINARY_DIR}/output1.cpp ${FOO_BINARY_DIR}/output2.h ${FOO_BINARY_DIR}/output3.cpp<br />
COMMAND ${MY_GENERATOR_EXE} ${FOO_BINARY_DIR} ${FOO_SOURCE_DIR}/input.txt<br />
DEPENDS my_generator<br />
MAIN_DEPENDENCY ${FOO_SOURCE_DIR}/input.txt<br />
)<br />
# now create an executable using the generated files<br />
ADD_EXECUTABLE(generated<br />
${FOO_BINARY_DIR}/output1.cpp<br />
${FOO_BINARY_DIR}/output2.h<br />
${FOO_BINARY_DIR}/output3.cpp)<br />
<br />
CMake 2.4 allows you to generate a header file. Because generated headers often cause unnecessary rebuilds, you should try to avoid them; consider using the CONFIGURE_FILE command to prepare the header at CMake time. If you must generate a header file, use code like this:<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/bar.h ${CMAKE_CURRENT_BINARY_DIR}/foo.h<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bar.h<br />
)<br />
ADD_EXECUTABLE(foo foo.c ${CMAKE_CURRENT_BINARY_DIR}/foo.h)<br />
<br />
This is like the first example above, except that it generates a header instead of a C file. The header might not exist when the build system scans foo.c's dependencies, so there is no way for CMake to know that this target requires foo.h unless we can tell it that foo.h may exist in the future. We give CMake this knowledge by listing the generated header file in the set of source files for the target. (This requires CMake 2.4. Previous versions of CMake required use of the OBJECT_DEPENDS source file property.)<br />
<br />
=== I use EXEC_PROGRAM but the result is not set in subdirectories. Why? ===<br />
<br />
An unfortunate holdover from ancient CMake versions is that certain commands are "inherited" into subdirectories and others are not. EXEC_PROGRAM is not inherited. What this means is that when the listfile code from a parent directory executes in a subdirectory the EXEC_PROGRAM command is left out. Therefore the code executes differently. This problem was fixed in CMake 2.2, but for older versions you will have to cache the result:<br />
<br />
<pre><br />
EXEC_PROGRAM(my-program OUTPUT_VARIABLE MY_OUTPUT)<br />
SET(MY_OUTPUT "${MY_OUTPUT}" CACHE INTERNAL "")<br />
</pre><br />
<br />
This will store the result in a global location so it will be available in the subdirectory. Be sure to choose a descriptive name for MY_OUTPUT to avoid conflict in the global setting.<br />
<br />
=== How can I get or set environment variables? ===<br />
<br />
CMake names environment variables using an ENV prefix and surrounding the names in curly braces. Here is an example:<br />
<br />
<pre><br />
MESSAGE("$ENV{PATH}")<br />
</pre><br />
<br />
Reading variables will work in any version of CMake. Writing to them works in CMake 2.2 and higher using the following syntax:<br />
<br />
<pre><br />
SET(ENV{HELLO} "World")<br />
</pre><br />
<br />
Note that there is currently no way to tell apart an empty environment variable value from a variable that is not set at all.<br />
<br />
One should avoid using environment variables for controlling the flow of CMake code (such as in IF commands). The build system generated by CMake may re-run CMake automatically when CMakeLists.txt files change. The environment in which this is executed is controlled by the build system and may not match that in which CMake was originally run. If you want to control build settings on the CMake command line, you need to use cache variables set with the -D option. The settings will be saved in CMakeCache.txt so that they don't have to be repeated every time CMake is run on the same build tree.<br />
<br />
Also, environment variables SET in the CMakeLists.txt ''only'' take effect for cmake itself, so you cannot use this method to set an environment variable that a custom command might need.<br />
<br />
=== Why do I have unwanted semicolons ; in my compiler flags? ===<br />
CMake has a list data type. A list is stored as a string of semicolon-separated list elements. Whitespace separated arguments to a SET statement are interpreted as list elements. For instance, SET(var a b c d e) will give "var" a value of a;b;c;d;e and this list can be used by other CMake commands. However, if you pass ${var} to a non-CMake external tool, such as a compiler's command line, you are passing a;b;c;d;e which is not what you want. Instead you either need to pass "${var}", so that the list will be converted to a whitespace-separated string, or you need to SET(var "a b c d e") in the 1st place so that you're working with a string, not a list.<br />
<br />
=== How can I get quoting and escapes to work properly? ===<br />
You may need \\ instead of \ due to CMake argument processing. \" works fine in SET statements, but you may need \\\" in some CMake functions. It can get hairy. This section needs elaboration.<br />
<br />
=== Isn't the "Expression" in the "ELSE (Expression)" confusing? ===<br />
Traditional CMakeLists.txt files require the following syntax. In the IF syntax, the ELSE section requires the same (Expression) as the IF section. This makes the script kind of hard to follow, for example:<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSE(WIN32)<br />
...do something else...<br />
ENDIF(WIN32)<br />
<br />
You might think that the ELSE section, here containing "...do something else...", is for the WIN32 portion of the script. That is not so! It is actually handling the NOT WIN32 section.<br />
<br />
If you find this too confusing you can enable the CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS option which will allow you to use a slightly more conventional syntax where the ELSE() and ENDIF() constructs can be empty:<br />
<br />
SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS true)<br />
<br />
IF(WIN32)<br />
...do something...<br />
ELSEIF(APPLE)<br />
...do something else...<br />
ELSE()<br />
...do something else...<br />
ENDIF()<br />
<br />
=== Which regular expressions are supported by CMake? ===<br />
When using MATCHES or MATCHALL in an IF command, or using any of the STRING(REGEX ...) commands, CMake expects regular expressions, not globs (wild cards). CMake uses the same regular expression engine above all platforms. Here are the meanings of the metacharacters:<br />
<br />
^ Matches at beginning of a line<br />
$ Matches at end of a line<br />
. Matches any single character<br />
[ ] Matches any character(s) inside the brackets<br />
[^ ] Matches any character(s) not inside the brackets<br />
- Matches any character in range on either side of a dash<br />
| Matches a pattern on either side of the |<br />
* Matches preceding pattern zero or more times<br />
+ Matches preceding pattern one or more times<br />
? Matches preceding pattern zero or once only<br />
() Saves a matched expression and uses it in a later match<br />
<br />
Example: "[-][L]([^ ;])+" matches all strings beginning with -L and ending with a space or a semicolon, the usual linkdirs under Linux.<br />
<br />
Here is how to catch a part of a string. The variable test is filled with some content, and then we want to catch the "me":<br />
<br />
SET(test "hello world ! catch: me if you can")<br />
STRING(REGEX REPLACE ".*catch: ([^ ]+).*" "\\1" result "${test}" )<br />
MESSAGE(STATUS "result= ${result}")<br />
<br />
This is slightly tricky. The part inside the brackets is available in \\1 . CMake will copy the variable test to the variable result, but then it will replace everything that the regular expression matches with \\1. This means the first regular expression has to match the whole string and the part we want to catch has to be put in parens.<br />
<br />
-- result= me<br />
<br />
For those of you who know Perl, the equivalent Perl code could be:<br />
<br />
$test = "hello world ! catch: me if you can";<br />
$result = $test;<br />
$result =~ s/.*catch: ([^ ]+).*/$1/;<br />
print "-- result= $result\n";<br />
<br />
There are other ways to do this in Perl, but this is how we do it in CMake because \\1 does not become a variable like $1 does in perl, so there is no SET(result ${\\1}) in CMake.<br />
<br />
=== How can I build multiple modes without switching ? ===<br />
To build multiple modes (e.g. Debug and Release) in one shot without constantly running cmake -DCMAKE_BUILD_TYPE=Debug and cmake -DCMAKE_BUILD_TYPE=Release in source tree create a directory for builds eg.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
</pre><br />
<br />
Inside you can place as many target directories for out-of-source build modes as you want, e.g.:<br />
<br />
<pre><br />
Project-directory/<br />
/Build<br />
/Debug<br />
/Release<br />
</pre><br />
<br />
In each of these directories issue a command (assuming that you have CMakeLists.txt directly in Project-directory)<br />
<br />
<pre><br />
cmake -DCMAKE_BUILD_TYPE=type_of_build ../../<br />
</pre><br />
<br />
to create a cmake cache configured for requested build type.<br />
<br />
Now you can make each build just by entering appropriate directory and executing a make command.<br />
<br />
=== How can I extend the build modes with a custom made one ? ===<br />
The following code snipet (taken from a CMakeLists.txt) adds a Maintainer mode:<br />
<pre><br />
SET( CMAKE_CXX_FLAGS_MAINTAINER "-Wall -Wabi" CACHE STRING<br />
"Flags used by the C++ compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_C_FLAGS_MAINTAINER "-Wall -pedantic" CACHE STRING<br />
"Flags used by the C compiler during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used for linking binaries during maintainer builds."<br />
FORCE )<br />
SET( CMAKE_SHARED_LINKER_FLAGS_MAINTAINER<br />
"-Wl,--warn-unresolved-symbols,--warn-once" CACHE STRING<br />
"Flags used by the shared libraries linker during maintainer builds."<br />
FORCE )<br />
MARK_AS_ADVANCED(<br />
CMAKE_CXX_FLAGS_MAINTAINER<br />
CMAKE_C_FLAGS_MAINTAINER<br />
CMAKE_EXE_LINKER_FLAGS_MAINTAINER<br />
CMAKE_SHARED_LINKER_FLAGS_MAINTAINER )<br />
# Update the documentation string of CMAKE_BUILD_TYPE for GUIs<br />
SET( CMAKE_BUILD_TYPE "" CACHE STRING<br />
"Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel Maintainer."<br />
FORCE )<br />
</pre><br />
Notes: this will only work with gcc (since the flags would need to be<br />
declined with the possible compilers). Additionaly this will override<br />
a CMAKE_BUILD_TYPE previously set in the CMakeLists.txt...<br />
<br />
== Writing FindXXX.cmake files ==<br />
<br />
=== What are the rules to write a FindXXX.cmake file? ===<br />
<br />
Let's follow the instructions and the advices in the <br />
Modules/readme.txt [http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?rev=1.12&root=CMake&view=markup]<br />
file located in the CVS repository. <br />
<br />
== Finding and using external packages ==<br />
<br />
=== How do I use CMake to generate SWIG wrapper libraries? ===<br />
<br />
CMake version 2 includes a module that supports the generation of SWIG wrapper libraries. The SWIG package defines the following macros: SWIG_ADD_MODULE and SWIG_LINK_LIBRARIES.<br />
<br />
<pre><br />
# This example shows how to use python<br />
# Currently these languages have been tested:<br />
# perl tcl ruby php4 pike<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
FIND_PACKAGE(PythonLibs)<br />
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(example python<br />
example.i example.cxx)<br />
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})<br />
<br />
</pre><br />
<br />
<pre><br />
# This example shows how to use tcl<br />
PROJECT(TCL_WRAP)<br />
SET ( MODULE_NAME project )<br />
SET ( INTERFACE_FILES project.i)<br />
SET ( SRC_FILES Vertex.h Vertex.cxx Shapes.h Shapes.cxx )<br />
<br />
FIND_PACKAGE(SWIG REQUIRED)<br />
INCLUDE(${SWIG_USE_FILE})<br />
<br />
# Look for TCL<br />
INCLUDE_DIRECTORIES(${TCL_INCLUDE_PATH})<br />
<br />
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80<br />
PATHS /usr/lib /usr/local/lib)<br />
IF (TCL_LIBRARY)<br />
TARGET_ADD_LIBRARY (${MODULE_NAME} TCL_LIBRARY)<br />
ENDIF (TCL_LIBRARY)<br />
<br />
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})<br />
<br />
SET(CMAKE_SWIG_FLAGS "-c++")<br />
<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CPLUSPLUS ON)<br />
SET_SOURCE_FILES_PROPERTIES(${INTERFACE_FILES} PROPERTIES CMAKE_SWIG_FLAGS "-includeall")<br />
SWIG_ADD_MODULE(${MODULE_NAME} tcl ${INTERFACE_FILES} ${SRC_FILES})<br />
SWIG_LINK_LIBRARIES(${MODULE_NAME} ${TCL_LIBRARIES})<br />
</pre><br />
<br />
=== How do I use CMake to build LaTeX documents? ===<br />
Use the following approach. Note that you have to set LATEX_COMPILE to LaTeX executable, DVIPDF_COMPILE to dvi to pdf converter. Also, the LaTeX source is TDocument.tex and the result is called TDocument.pdf. Note that this uses commands in CMake version 1.8 or later.<br />
<br />
PROJECT(Document)<br />
IF(LATEX_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.tex<br />
COMMAND ${LATEX_COMPILE} <br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex <br />
)<br />
ENDIF(LATEX_COMPILE)<br />
<br />
IF(DVIPDF_COMPILE)<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi <br />
COMMAND ${DVIPDF_COMPILE}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.dvi<br />
)<br />
ENDIF(DVIPDF_COMPILE)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
<br />
The following uses commands in CMake version 2.0 and later<br />
<br />
PROJECT(Document)<br />
# <br />
# Find LaTeX<br />
#<br />
FIND_PACKAGE(LATEX)<br />
<br />
IF(LATEX_COMPILER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS ${Document_SOURCE_DIR}/TDocument.tex<br />
DEPENDS ${Document_SOURCE_DIR}/TDocument.tex<br />
COMMENT "Tex2dvi"<br />
)<br />
<br />
IF(DVIPS_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.ps<br />
COMMAND ${DVIPS_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.dvi<br />
-o ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.dvi<br />
COMMENT "dvi2ps"<br />
)<br />
<br />
IF(PS2PDF_CONVERTER)<br />
ADD_CUSTOM_COMMAND( <br />
OUTPUT ${Document_BINARY_DIR}/TDocument.pdf<br />
COMMAND ${PS2PDF_CONVERTER}<br />
ARGS ${Document_BINARY_DIR}/TDocument.ps<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.ps<br />
COMMENT "ps2pdf"<br />
)<br />
<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${Document_BINARY_DIR}/TDocument.pdf<br />
)<br />
ENDIF(PS2PDF_CONVERTER)<br />
ENDIF(DVIPS_CONVERTER)<br />
ENDIF(LATEX_COMPILER)<br />
<br />
=== How do I get LaTeX references to be correct? ===<br />
When your latex document contains references (e.g. \ref{...} command) you get to run two passes of latex. In the<br />
most general case, i.e. when additionally your document uses a bibtex bibliography, you shall need three<br />
passes of latex (and one pass of bibtex):<br />
# latex (first pass: for bibtex to have an .aux file)<br />
# bibtex (for generating the .bbl file)<br />
# latex (second pass)<br />
# latex (third pass)<br />
<br />
The following code snippet illustrates how you can "pervert" the bibtex and latex generated<br />
auxilary files (.aux, .log, .dvi, .bbl...) to create an "artificial" set of CMake dependencies.<br />
The side-effect of those dependencies should hopefully be the above described sequence of calls<br />
to latex and bibtex<br />
<pre><br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/UsersManual.tex<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (first pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.aux<br />
COMMAND ${BIBTEX_COMPILER}<br />
ARGS -terse ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Bibtex"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (second pass)"<br />
)<br />
<br />
ADD_CUSTOM_COMMAND(<br />
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.bbl<br />
${CMAKE_CURRENT_BINARY_DIR}/UsersManual.dvi<br />
COMMAND ${LATEX_COMPILER}<br />
ARGS -interaction=batchmode ${CMAKE_CURRENT_BINARY_DIR}/UsersManual<br />
COMMENT "Latex (third pass)"<br />
)<br />
# Eventually trigger the whole process<br />
ADD_CUSTOM_TARGET(LaTeXDocument ALL echo<br />
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/UsersManual.log<br />
)<br />
</pre><br />
<br />
=== How can I set TEXINPUTS for a LaTeX compilation? ===<br />
First note that most often you can avoid using TEXINPUTS by copying all the necessary files (.tex source file and<br />
included graphic files e.g. .eps files) from your PROJECT_SOURCE_DIR hirarchy to your PROJECT_BINARY_DIR subdir<br />
[refer to CONFIGURE_FILE with the COPYONLY flag set for copying files]. Since by default latex uses the current working directory as value for TEXINPUTS you should be all set. As expected, this trick is quick AND dirty since your<br />
concerned PROJECT_BINARY_DIR subdir now contains files that are NOT generated by CMake (in the sense that those<br />
files are not the result of a system command but were merely duplicated)... <br />
<br />
If you consider it is cleaner or easier to define a TEXINPUTS environment variable [the latex command probably<br />
misses a -I flag] you can find an example in the InsightDocuments cvs archive (refer to the section "cvs access"<br />
near the bottom of Kitware's ITK download page) or use google with keywords "ITK_TEXINPUTS CONFIGURE_FILE".<br />
Look at InsightDocuments/CourseWare/Training/Vis2003/Latex/CMakeLists.txt and search for e.g. "LaTeXWrapper.sh.in".<br />
<br />
Roughly the mechanism goes:<br />
* SET ITK_TEXINPUTS with the desired TEXINPUTS<br />
* CONFIGURE_FILE "InsightDocuments/CourseWare/Training/Vis2003/LaTeXWrapper.sh.in" which generates an sh shell script setting the shell variable TEXINPUTS prior to running the latex command<br />
* use ADD_CUSTOM_COMMAND to invoke this shell script<br />
This very example is Win32 portable (except that LaTeXWrapper.bat.in generates a .bat shell script)<br />
<br />
== Library questions ==<br />
<br />
=== Can I build both shared and static libraries with one ADD_LIBRARY command? ===<br />
<br />
No. Each library you build must have a unique target name, i.e. the "libname" field of the ADD_LIBRARY command. That way, CMake can track dependencies separately for each library. Libraries can have the same OUTPUT_NAME, see the SET_TARGET_PROPERTIES command, but this is not the default.<br />
<br />
=== Does that mean I have to build all my library objects twice, once for shared and once for static?! I don't like that! ===<br />
<br />
In practice, most libraries have different defines and compiler flags for the shared vs. static cases. So you would have to build all your library objects twice anyways. However, if you happen to have '''''exactly''''' the same defines and compiler flags for the shared vs. static cases...<br />
<br />
...if you're using Linux and a GCC-style linker, you could do the following. Note that for this to work correctly on linux, the zzSTATIC source files should have been compiled with "-fPIC" to ensure they will work in a shared library.<br />
<br />
IF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
ADD_LIBRARY(zzSTATIC STATIC -fPIC)<br />
ADD_LIBRARY(zzDYNAMIC SHARED)<br />
TARGET_LINK_LIBRARIES(zzDYNAMIC -Wl,-whole-archive zzSTATIC -Wl,-no-whole-archive)<br />
ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_COMPILER_IS_GNUCC)<br />
<br />
...if you want a cross-platform approach that works on all compilers, not just GCC or Linux, you could extract the locations of previously built object files and insert them directly into the libraries that need them. This is documented in [http://www.cmake.org/Bug/view.php?id=5155 CMake Feature Request #5155: standard way to locate object files]. Unfortunately this approach relies on CMake's internal implementation, and that implementation could change in the future, breaking your code.<br />
<br />
=== How do I make my shared and static libraries have the same root name, but different suffixes? ===<br />
Set the OUTPUT_NAME of your shared and static libraries to the same thing.<br />
<br />
ADD_LIBRARY(foo SHARED ${foo_sources})<br />
ADD_LIBRARY(foo-static STATIC ${foo_sources})<br />
// The library target "foo" already has a default OUTPUT_NAME of "foo", so we don't need to change it.<br />
// The library target "foo-static" has a default OUTPUT_NAME of "foo-static", so change it.<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES OUTPUT_NAME "foo")<br />
<br />
If you are building your shared and static libraries in the same directory, you will also need the following to keep your shared and static libraries from clobbering each other during the build.<br />
<br />
SET_TARGET_PROPERTIES(foo PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
SET_TARGET_PROPERTIES(foo-static PROPERTIES CLEAN_DIRECT_OUTPUT 1)<br />
<br />
=== How do I rename a library after it has already been built? ===<br />
You don't rename it. It's been built! Its name is whatever CMakeLists.txt says it's supposed to be.<br />
<br />
Perhaps you want to copy the library to a different name. But, are you sure that's what you want to do? You could just change the name in your ADD_LIBRARY command or change its OUTPUT_NAME property using SET_TARGET_PROPERTY(). If you really really want to copy the library to a different name, try:<br />
<br />
GET_TARGET_PROPERTY(LIB_NAME Foo LOCATION)<br />
GET_TARGET_PROPERTY(Bar_prefix Foo PREFIX)<br />
GET_TARGET_PROPERTY(Bar_suffix Foo SUFFIX)<br />
SET(NEW_LIB_NAME ${Bar_prefix}Bar${Bar_suffix})<br />
<br />
ADD_CUSTOM_COMMAND(<br />
TARGET Foo<br />
POST_BUILD<br />
COMMAND ${CMAKE_COMMAND} -E copy ${LIB_NAME} ${NEW_LIB_NAME}<br />
)<br />
<br />
On Windows you may also want to copy the .dll import lib, using the same approach as above, but with IMPORT_PREFIX and IMPORT_SUFFIX. ''Problem: LOCATION only refers to 1 file, the .dll. What is a simple way to get the location of the import lib? Could provide a complicated way, but that's annoying.''<br />
<br />
=== Does CMake support "convenience" libraries? ===<br />
No. CMake does not currently support convenience libraries. A "convenience" library, as GNU libtool calls it, is an archive of objects to be mixed into other libraries. Other libraries "link" to the convenience library, but the convenience library does not export any symbols; GNU libtool never installs the convenience library; no programs ever link to the convenience library.<br />
<br />
This does '''not''' mean that a project using convenience libraries cannot be converted to CMake. Instead the source files may be listed in each target that needs them. They will be built for each target separately using all the preprocessor definitions and flags configured for that target.<br />
<br />
=== Why are libraries linked to my shared library included when something links to it? ===<br />
This question arises when one has a library B which links to some library A. When a third target, say C, links to B, CMake will automatically include C to A also. When the libraries are static, then this is always necessary. When the libraries are shared, then this is necessary on some platforms but not others. The decision was made to make this consistent across all platforms and library types for simplicity and reliability.<br />
<br />
We have never seen a real case when this causes a problem. The most commonly suggested example is when A is a static library then both B and C get copies of it. On most platforms this is already an error because it is not safe to link static libraries into shared libraries: there is no way to ensure that the static libraries contain relocatable objects (built with -fPIC or equivalent flag).<br />
<br />
In the future CMake may distinguish between the linking interface (what libraries are needed for C to use library B) and the linking implementation (what libraries are needed to create B in the first place). This has not yet been implemented.<br />
<br />
=== CMake dependency scanner ===<br />
<br />
CMake has a limited support for scanning dependencies. Currently it does not support:<br />
* Preprocessor macro<br />
<pre><br />
#if 0<br />
# include "bla.h"<br />
#endif<br />
</pre><br />
* Fixed form comment (fortran 77/90/95)<br />
C USE bla<br />
<br />
== Installation questions ==<br />
<br />
=== Does CMake's "make install" support DESTDIR? ===<br />
Yes, when a makefile generator is used. After the build completes, one may run "make install" to install any files the project configured to be installed. Running<br />
<br />
make install DESTDIR="/home/me/mydist"<br />
<br />
will cause the installation to copy files to "/home/me/mydist/${CMAKE_INSTALL_PREFIX}/...". This is useful for package maintainers.<br />
<br />
=== Can I do "make uninstall" with CMake?===<br />
By default, CMake does not provide the "make uninstall" target, so you cannot do this. We do not want "make uninstall" to remove useful files from the system.<br />
<br />
If you want an "uninstall" target in your project, then nobody prevents you from providing one. You need to delete the files listed in install_manifest.txt file. Here is how to do it. First create file cmake_uninstall.cmake.in in the top-level directory of the project:<br />
<br />
<pre><br />
IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")<br />
ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")<br />
<br />
FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)<br />
STRING(REGEX REPLACE "\n" ";" files "${files}")<br />
FOREACH(file ${files})<br />
MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")<br />
IF(EXISTS "$ENV{DESTDIR}${file}")<br />
EXEC_PROGRAM(<br />
"@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""<br />
OUTPUT_VARIABLE rm_out<br />
RETURN_VALUE rm_retval<br />
)<br />
IF(NOT "${rm_retval}" STREQUAL 0)<br />
MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")<br />
ENDIF(NOT "${rm_retval}" STREQUAL 0)<br />
ELSE(EXISTS "$ENV{DESTDIR}${file}")<br />
MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")<br />
ENDIF(EXISTS "$ENV{DESTDIR}${file}")<br />
ENDFOREACH(file)<br />
</pre><br />
<br />
Then in the top-level CMakeLists.txt add the following logic:<br />
<br />
<pre><br />
CONFIGURE_FILE(<br />
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"<br />
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"<br />
IMMEDIATE @ONLY)<br />
<br />
ADD_CUSTOM_TARGET(uninstall<br />
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")<br />
</pre><br />
<br />
Now you will have an "uninstall" target at the top-level directory of your build tree.<br />
<br />
Instead of creating an "uninstall" target, Unix users could enter this command in the shell:<br />
<br />
xargs rm < install_manifest.txt<br />
<br />
== Distribution questions ==<br />
<br />
=== Where is "make dist"? ===<br />
<br />
CMake doesn't create a "make dist" target.<br />
<br />
=== What is the best way to distribute source code or binaries for a cmake-based project? ===<br />
<br />
For creating source or binary packages there is now [[CMake#CPack | CPack]] coming with CMake, see the <br />
[[ CMake#CPack | documentation]].<br />
<br />
Of course you can also use any other ways to create packages.<br />
<br />
== Platform-specific questions ==<br />
=== How do I build universal binaries on Mac OS X? ===<br />
Before running CMake with an empty build tree, set the CMAKE_OSX_ARCHITECTURES environment variable. It should be set to contain a ; separated list of architectures that you want in the binary. For example, for a power pc and Intel 386 you would do this:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386<br />
<br />
You can also set the same named CMake cache variable on an existing binary tree. This works with both makefiles and the Xcode generator. <br />
<br />
In addition, you can also set the CMAKE_OSX_SYSROOT variable to point to the sysroot to be used. CMake will attempt to pick one on your system, but it can be changed in the cache or via an environment variable before running CMake.<br />
<br />
<br />
=== How can I apply resources on Mac OS X automatically? ===<br />
Using ADD_CUSTOM_COMMAND. For example, let's say you are creating executable MyExecutable, which needs the resources file Carbon.r. All you do is add a custom rule which is executed after the executable is linked:<br />
<br />
<pre><br />
ADD_EXECUTABLE(MyExecutable ${MyExecutable_SRCS})<br />
GET_TARGET_PROPERTY(MyExecutable_PATH MyExecutable LOCATION)<br />
<br />
IF(APPLE)<br />
FIND_PROGRAM(APPLE_RESOURCE Rez /Developer/Tools)<br />
IF(APPLE_RESOURCE)<br />
ADD_CUSTOM_COMMAND(TARGET MyExecutable POST_BUILD<br />
COMMAND ${APPLE_RESOURCE} Carbon.r -o ${MyExecutable_PATH})<br />
ENDIF(APPLE_RESOURCE)<br />
ENDIF(APPLE)<br />
</pre><br />
<br />
This will execute:<br />
<br />
/Developer/Tools/Rez Carbon.r -o /binary/path/MyExecutable<br />
<br />
after MyExecutable is linked.<br />
<br />
'Rez' may be located elsewhere on disk, depending on the version of Mac OS X and Xcode. You can use 'which Rez' in Terminal to find it's full path.<br />
<br />
=== Why does FIND_LIBRARY not find .DLL libraries under WIN32? ===<br />
For those who come from a Unix background to MS Windows:<br />
<br />
You never link directly to the .dll, you have to link against the import library .lib for the .dll.<br />
<br />
Linking against dynamic libraries (.dll under Windows) is quite different from linking against ELF shared objects (.so) under platforms like Linux or NetBSD. In Windows, there are two types of library, a static library and an import library (both confusingly use the .lib extension, however). In Windows, when you build an import library (A.lib) you will get a corresponding (A.dll) that you only need at runtime. At compile time you will need the import library.<br />
<br />
Conclusion: There is no need to find a .dll for linking. You only need to find the .lib import library.<br />
<br />
Some more details can be found here: [http://xenophilia.org/winvunix.html].<br />
<br />
=== Why am I getting a linker error to _mainCRTStartup under WIN32? ===<br />
Your program is a GUI application using WinMain (/subsystem:windows) and not a console application using main. You have to use the WIN32 option with the ADD_EXECUTABLE command.<br />
<br />
ADD_EXECUTABLE(exename WIN32 source1 source2 ... sourceN)<br />
<br />
The second argument to ADD_EXECUTABLE can be WIN32. This indicates that the executable, when compiled on Windows, is a Windows app (using WinMain) and not a console app (using main). Please note that on Unix platforms, CMake ignores the WIN32 and the compiler will use "main" in any case.<br />
<br />
=== Why do I get this error: nafxcwd.lib(appcore.obj) : error LNK2001: unresolved external symbol ___argv ===<br />
<br />
This is because the application is using both the static and dll versions of the MFC library.<br />
To fix the problem, you can do the following:<br />
<br />
SET(CMAKE_MFC_FLAG 2) # force the IDE to use static MFC<br />
ADD_DEFINITIONS(-D_AFXDLL) # make sure if afx.h is included the dll MFC is used<br />
<br />
=== How to use MFC with CMake ===<br />
To use MFC, the CMAKE_MFC_FLAG variable must be set as follows:<br />
<br />
0: Use Standard Windows Libraries<br />
1: Use MFC in a Static Library<br />
2: Use MFC in a Shared DLL <br />
<br />
This can be set in a CMakeLists.txt file and will enable MFC in the application. It should be set to 1 or 2. This is used in visual studio 6 and 7 project files. The CMakeSetup dialog uses MFC and the CMakeLists.txt looks like this:<br />
<br />
ADD_DEFINITIONS(-D_AFXDLL)<br />
SET(CMAKE_MFC_FLAG 2) <br />
ADD_EXECUTABLE(CMakeSetup WIN32 ${SRCS})<br />
<br />
=== How To Put Files in Folders in Visual Studio Projects ===<br />
The Visual Studio IDE supports putting files into folders.<br />
CMake can be used to put files in folders with the SOURCE_GROUP <br />
command. <br />
<br />
SOURCE_GROUP(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])<br />
<br />
Defines a group into which sources will be placed in project files. This is mainly used to setup file tabs in Visual Studio. Any file whose name is listed or matches the regular expression will be placed in this group provided the source file is being passed to ADD_EXECUTABLE or ADD_LIBRARY.<br />
<br />
For example:<br />
SOURCE_GROUP(FooFiles FILES foo.cxx)<br />
SOURCE_GROUP(BarFiles FILES bar.cxx)<br />
ADD_LIBRARY(foo foo.cxx bar.cxx)<br />
<br />
In the event a file matches multiple groups, the LAST group that explicitly lists the file will be favored, if any. If no group explicitly lists the file, the LAST group whose regular expression matches the file will be favored. For backwards compatibility this command is also supports the format SOURCE_GROUP(name regex).<br />
<br />
As a convenience to developers CMake automatically adds standard header files to a "Header Files" folder and standard source files to a "Source Files" folder for Visual Studio Projects. This can be overridden via the SOURCE_GROUP method documented above.<br />
<br />
=== How to create Visual Studio 6 Projects that contain only a single build type===<br />
For Visual Studio.NET (version 7.0 and above) it is possible to set the CMAKE_CONFIGURATION_TYPES variable to the build type(s) (Debug/Release/...) that you want. This does not work for Visual Studio 6. There is however a way to achieve this. To create your own set of configurations:<br />
<br />
# Create a directory in which you copy the files *.dsptemplate and CMakeVisualStudio6Configurations.cmake from CMake's Templates directory.<br />
# Edit the .cmake file and change the SET(CMAKE_CONFIGURATION_TYPES ...) line to set the build types that you want in your set.<br />
# Edit the *Header.dsptemplate files to contain only the configuration types you want in your set.<br />
# In your CMakeLists.txt file, set the MSPROJECT_TEMPLATE_DIRECTORY to the directory that you created.<br />
<br />
<br />
That's it. Run CMake and your new configuration files will be created.<br />
<br />
Note: Editing the *Header.dsptemplates files should be done very carefully. Here are some guidelines:<br />
<br />
- You MUST remove the targets that you do not want in your set at the bottom of the file (e.g. '# Name "OUTPUT_LIBNAME - Win32 MinSizeRel"')<br />
- You can remove the '!IF "$(CFG)" == ...' until '!ELSEIF "$(CFG)" == ...' or '!ELSEIF "$(CFG)" == ...' until '!ENDIF' lines for the configurations you do not want. Make sure that the resulting code still starts with '!IF ...' and ends with '!ENDIF' with any number of '!ELSEIF' sections in between. If you create templates for a single configuration (aka makefile), it is possible to remove everything starting from '!IF' until and including '!ENDIF' and leave only the contents of the relevant section intact.<br />
- Do not edit the lines starting with '!MESSAGE' as the changes may - and probably will - corrupt your resulting DSP files. The only thing I was able to change without corrupting the DSP is to remove the irrevant configurations from the "Possible choices for configuration are:" list.<br />
<br />
If you have only a single configuration in your set, you may want to get rid of the intermediate dir that MsDev creates. You can do that by setting:<br />
# PROP BASE Output_Dir ""<br />
# PROP BASE Intermediate_Dir ""<br />
# PROP Intermediate_Dir ""<br />
# PROP Output_Dir "LIBRARY_OUTPUT_PATH"<br />
or<br />
# PROP Output_Dir "EXECUTABLE_OUTPUT_PATH"<br />
<br />
Additionally you should then also edit the '# ADD LINK32' line in the DLLHeader.dsptemplate file. Change for example '/out:"LIBRARY_OUTPUT_PATHDebug/OUTPUT_LIBNAMEDEBUG_POSTFIX.dll"' into '/out:"LIBRARY_OUTPUT_PATHOUTPUT_LIBNAMEDEBUG_POSTFIX.dll"' (Note that the configuration name and also the slash are removed).<br />
<br />
It is even possible to rename the pre-defined configurations of CMake in this way. Let's say you prefer 'PreProduction' over 'RelWithDebInfo'. You can change the name in the *.dsptemplate files, but you should also change it in the CMakeVisualStudio6Configurations.cmake file. Be careful, however. Only entries relevant to the configuration name should be changed. Do not change the /debug options and the entries that contain the build type in capital characters. Internally in CMake the build type will still remain 'RelWithDebInfo', so also the CMAKE_BUILD_TYPE should be set to the old value. You can only change the way it is named in MSDev.<br />
<br />
Note: Apparently MsDev as command-line build tool only performs a partial check on the build type. It will match all configuration types that CONTAIN the build type in their name. (e.g. if you have renamed RelWithDebInfo to DebugRelease, Debug will build Debug and DebugRelease, Release will build Release and DebugRelease. This may be exactly what you want, but be warned.)<br />
<br />
=== Can CMake set the Debugging/Working Directory property in Visual Studio projects? ===<br />
<br />
No. The value of this property is not stored in the project files. It is stored in extra files created by the IDE when a solution is loaded (VS .NET 2003 uses a hidden .suo file next to the .sln solution file). The format of these files is not known to CMake and cannot be generated. In some versions of VS the files are binary and not human readable.<br />
<br />
=== Why does CMakeSetup with the message "LINK : fatal error LNK1104: cannot open file 'user32.lib'" while configuring a project? ===<br />
<br />
The path to the SDK libs (user32.lib) must be added by the IDE when the<br />
project generator "Visual Studio 8 2005" is used, because cmake uses<br />
VCExpress.exe and on the fly generated project files to check<br />
for compiling (VCExpress.exe reads some config files for the<br />
compiler/linker options)<br />
<br />
So add the sdk lib path (...\Microsoft Platform SDK\Lib) at Tools->Options->Projects and Solutions->VC++ Directories->Library files<br />
<br />
See also:<br />
*http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/<br />
<br />
=== How can I avoid the error "Arg list too long" when running make? ===<br />
This error is sometimes encountered when building a static library with many object files using Unix make command. It typically looks something like this:<br />
<br />
<pre><br />
gmake[2]: execvp: /bin/sh: Arg list too long<br />
</pre><br />
<br />
When make tries to run the archiver program to build the static library the shell it uses complains that the argument list is too long. In some shells this can be fixed by setting an environment variable such as <tt>ARG_MAX</tt> to extend the length of the command line it will allow.<br />
<br />
=== How can I find out platforms definitions, search paths, etc. from gcc ?===<br />
<br />
The following is really the best if not only way to get information about predefined macros with a GNU compiler:<br />
<pre><br />
$ touch empty.c<br />
$ gcc -v -dD -E empty.c <br />
</pre><br />
This will give you all you might want to know about the preprocessor, the builtin include search dirs and all<br />
predefined definitions, so you can check whether it's __LINUX or _LINUX_ or _APPLE_ or __APPLE etc. <br />
The empty file and all these parameters are really required. You probably want to pipe the output (both stdout and stderr) to a file.<br />
<br />
This is how you can get the builtin library search paths:<br />
<pre><br />
$ gcc --print-search-dirs<br />
</pre><br />
<br />
=== How can I get a windows registry key ?===<br />
<br />
The only thing to know is that you can't use just the "SET" command in place of "GET" command.<br />
CMake read the value from the registry only when you "get" it from the cache. For instance :<br />
<br />
<pre><br />
GET_FILENAME_COMPONENT(SDK_ROOT_PATH "[HKEY_LOCAL_MACHINE\\SOFTWARE\\PACKAGE;Install_Dir]" ABSOLUTE CACHE)<br />
</pre><br />
<br />
If a key name (ex: Install_Dir in this case) was not specified , the Default key value will be get.<br />
Now you could use the SDK_ROOT_PATH to add include and lib path to your project :<br />
<br />
<pre><br />
INCLUDE_DIRECTORIES(<br />
${SDK_ROOT_PATH}/include<br />
)<br />
<br />
LINK_DIRECTORIES(<br />
${SDK_ROOT_PATH}/lib<br />
)<br />
</pre><br />
<br />
You can also read a registry key in the PATHS section of a FIND_LIBRARY, FIND_PATH, FIND_PROGRAM, or FIND_FILE command<br />
FIND_FILE(BOOT_DOT_INI boot.ini PATHS [HKEY_CURRENT_USER\\Environment;HOMEDRIVE])<br />
<br />
For other examples have a look in the CMake Modules folder :<br />
- FindJava.cmake<br />
- FindPythonLibs.cmake<br />
- ..<br />
<br />
{{CMake/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=11004VTK/FAQ2007-12-13T20:12:51Z<p>Seanmcbride: /* How to get keyboard events working on Mac OS X? */</p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk is 5.0.3. This release is available at:<br />
<br />
http://www.vtk.org/files/release/5.0/<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly/<br />
<br />
See http://www.vtk.org/get-software.php for more information.<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesisitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Can I contribute money? ===<br />
<br />
Please don't send money. Not that we think you're going to send in<br />
unsolicited money. But if you were thinking about it, stop. It would<br />
just complicate our lives and make for all sorts of tax problems.<br />
<br />
(Note: if you are a company or funding institution, and would like to fund<br />
features or development, please contact Kitware http://www.kitware.com .)<br />
<br />
=== Is there a mailing list or Usenet newsgroup for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
There is also a newsgroup that mirrors the mailinglist. At this point it<br />
seems that mirror is down. Mail to the mailinglist used to be posted the<br />
newsgroup, but posts on the newsgroup were not sent to the mailinglist.<br />
The newsgroup was located at:<br />
news://scully.esat.kuleuven.ac.be/vtk.mailinglist<br />
<br />
http://www.gmane.org is a bidirectional mail-to-news gateway that carries the vtkusers mailing list. Its located here: news://news.gmane.org/gmane.comp.lib.vtk.user or here: http://news.gmane.org/gmane.comp.lib.vtk.user. vtkusers mails have been archived since April 2002 and they never expire. You can read and send mails to the vtkusers list but sent mail will bounce back without having subscribed to the list first.<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://public.kitware.com/dashboard.php?name=vtk<br />
<br />
VTK uses Dart to perform builds, run tests, and generate dashboards. You<br />
can find more information about Dart at: http://public.kitware.com/Dart/<br />
<br />
You can help improve the quality of VTK by supplying the authors with<br />
Tcl scripts that can be used as or turned into regression tests. A good<br />
regression test will:<br />
<br />
# Cover code that is not already covered.<br />
# Illustrate a bug that is occuring now or that has occurred in the past.<br />
# Use data that is on the 2nd Edition book CDROM or use "small" data files or use no data at all.<br />
# Optionally, produce an interesting result. <br />
<br />
Currently almost all regression tests are written in Tcl.<br />
<br />
Please send your Tcl regression tests to:<br />
mailto:wlorens1@mail.nycap.rr.com<br />
<br />
Bill will evaluate them for applicability and integrate them into the<br />
nightly test process.<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are five things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and work through the examples (there are 400-500 examples). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled "How to ask questions the smart<br />
way". Read it here:<br />
<br />
http://www.catb.org/~esr/faqs/smart-questions.html<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Avoid HTML emails.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
bacause the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Developement]]<br />
<br />
=== Accessing VTK CVS from behind a firewall ===<br />
<br />
Use the sourceforge project:<br />
<br />
http://cvsgrab.sourceforge.net/<br />
<br />
Just download the script and type something like:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xx<br />
<br />
(Thanks to Ingo H. de Boer)<br />
<br />
Also cvsgrab support the following option to access a particular branch:<br />
<br />
-tag <version tag> [optional] The version tag of the files to download<br />
<br />
For example to get the latest 4.4 branch:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xxx<br />
-tag release-4-4<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# 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.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
http://www.google.com/url?sa=D&q=http%3A%2F%2Fpublic.kitware.com%2Fpipermail%2Fvtkusers%2F2003-October%2F070054.html<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# 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''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
For a more elaborate DICOM library that supports compressed jpeg, you might try [http://www.creatis.insa-lyon.fr/Public/Gdcm/ Gdcm].<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
1) Using ReleaseDataFlag<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
2) Use ImmediateModeRendering<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
3) Use triangle strips via vtkStripper.<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
4) Use a different filter or mapper<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use STL. However, the following policy<br />
applies.<br />
<br />
# 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.<br />
# 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.<br />
# Include the VTK wrapper header files: vtkstd/map instead of map.<br />
# Use the vtkstd:: namespace to refer to STL classes and functions.<br />
<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| MPEG2 || || vtkMPEG2Writer<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows and Mac workstations.<br />
<br />
=== What Graphics Cards work with VTK ===<br />
<br />
VTK uses OpenGL to perform almost all of its rendering and some graphics cards/drivers have better support for OpenGL than others. This is not a listing of what cards perform well. It is a listing of what cards actually produce correct results. Here is a list of cards and their status roughly in best to worst order.<br />
<br />
* Any Nvidia desktop card on Windows -- 100% compatible<br /> <br />
* Any ATI desktop cards on Windows -- 100% compatible<br /><br />
* Mesa -- most releases pass all VTK tests<br /><br />
* Microsoft Software OpenGL -- passes all VTK tests but does have a couple bugs<br /><br />
* Mac graphics cards -- these usually pass all VTK tests. Older cards may have some issues, for example, the ATI Rage 128 Pro does not support textures larger than 1024x1024.<br /><br />
* Non-linux UNIX cards (Sun HP SGI) -- These generally work<br /><br />
* Any Nvidia card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Any ATI card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Nvidia laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests<br /><br />
* ATI laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests (e.g. [http://public.kitware.com/pipermail/vtkusers/2004-August/075966.html ATI Mobility Radeon 9600])<br /><br />
* Intel Extreme Graphics -- fails some VTK tests<br /><br />
<br />
=== How do I build the examples on the PC running Windows? ===<br />
<br />
Since building the C++ examples on the PC isn't all that easy, here are<br />
some instructions from Jack McInerney.<br />
<br />
Steps for creating a VTK C++ project 8/14/96<br />
<br />
This is based on what I learned creating a project to run the Mace<br />
example. These steps allowed me to successfully built and run this example.<br />
<br />
# Create a console project (File, New, then select Console application).<br />
# Add the files of interest to the project. (e.g., Mace.cxx)<br />
# Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies<br /> 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<br />
# 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).<br />
# 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 <br /> This is a self extracting archive which contains these files. Simply place them in your windows system directory.<br />
# Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless<br /><br />
<br />
When you go to run the program, it will bomb out unless it can find 2<br />
DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the<br />
project directory or the C:\WINDOWS directory. These files are supplied<br />
on the vtk CD-ROM (in the vtk\bin directory).<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
vtk builds on 64 bit systems, that is, systems where sizeof(void*) is 64 bits. However, parts of the vtk codebase are not 64 bit clean and so runtime problems are likely if that code is used.<br />
<br />
===== General =====<br />
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.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work reasonably with 64 bit Cocoa.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== What size swap space should I use on a PC? ===<br />
<br />
Building vtk on the PC requires a significant amount of memory (at least<br />
when using Visual C++)... but the final product is nice and compact. To<br />
build vtk on the PC, we recommend setting the min/max swap space to at<br />
least 400MB/500MB (depending on how much RAM you have... the sum of RAM<br />
and swap space should be roughly 500+ MB).<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
Struggled a few hours to get VTK to do offscreen rendering. I use it to<br />
batch process medical images. Without actually producing output on the<br />
screen, I still print resulting images in a report to easily review the<br />
results of an experiment.<br />
<br />
Here is how I solved this problem for VTK version 4.2.2.<br />
<br />
1. Download Mesa-4.0.4 source<br />
<br />
Modify Mesa-4.0.4/Make-config in the 'linux:' target the following vars:<br />
<br />
GL_LIB = libVTKMesaGL.so<br />
GLU_LIB = libVTKMesaGLU.so<br />
GLUT_LIB = libVTKMesaglut.so<br />
GLW_LIB = libVTKMesaGLw.so<br />
OSMESA_LIB = libOSVTKMesa.so<br />
<br />
In Mesa 6.2.1 you need to edit Mesa/configs/default instead:<br />
<br />
# Library names (base name)<br />
GL_LIB = VTKMesaGL<br />
GLU_LIB = VTKMesaGLU<br />
GLUT_LIB = VTKMesaglut<br />
GLW_LIB = VTKMesaGLw<br />
OSMESA_LIB = VTKMesaOSMesa<br />
<br />
<br />
And then export this env var:<br />
<br />
export 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"<br />
<br />
then<br />
<br />
For Mesa 4.0.4<br />
<br />
make -f Makefile.X11 linux <br />
cp Mesa-4.0.4/lib/* /data/usr/mesa404/lib/<br />
<br />
in Mesa 6.2.1:<br />
<br />
make linux-x86<br />
make install<br />
(I generally use /opt/VTKMesa/*)<br />
<br />
I use 'VTKMesa' name extension to avoid conflicts with my RH9.0 libs<br />
(especially OSMesa lib in XFree!). I'm using shared libraries, because<br />
that allows me to use dynamic libs from VTK and not the vtk program<br />
itself without explicitly having to load VTKMesaGL with my app. I copied<br />
the 'VTKMesa' libs in /data/usr/mesa404/lib/, but any odd place probably<br />
will work. Avoid /usr/lib /usr/local/lib for now.<br />
<br />
2. Follow normal instructions to get a proper working vtk, then<br />
<br />
ccmake <br />
<br />
with the following options:<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
| VTK_USE_MANGLED_MESA || ON<br />
|-<br />
| MANGLED_MESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_MESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaGL.so<br />
|-<br />
| MANGLED_OSMESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_OSMESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaOSMesa.so<br />
|-<br />
| OPENGL_xmesa_INCLUDE_DIR || /data/usr/mesa404/include<br />
|}<br />
<br />
test using /data/prog/VTK-4.2.2/Examples/MangledMesa/Tcl scripts<br />
<br />
<br />
If you're doing things on UNIX, you should also look at [[VTK Classes]]. It has links to RenderWindow objects that are probably easier to use than rebuilding VTK with Mesa.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
On Mac OS X, there are (at least) two kinds of executables:<br />
* [http://developer.apple.com/documentation/MacOSX/Conceptual/BPInternational/Articles/InternatSupport.html#//apple_ref/doc/uid/20000278-73764 Application Bundles]<br />
* plain UNIX executables<br />
<br />
For a program to be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction) it really should be an Application Bundle. If a plain UNIX executable tries, there will be various bugs, such as keyboard and mouse events not working reliably.<br />
<br />
Many, but not all, of the example VTK applications are built as plain UNIX executables, and thus have these problems. This is [http://www.vtk.org/Bug/bug.php?op=show&bugid=2025 VTK bug 2025].<br />
<br />
When you build your own VTK application, it is best to make it in the form of an Application Bundle. With CMake 2.0.5 or later, simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
If for some reason you cannot build as an Application Bundle (perhaps because your app needs command line parameters) you might be able to avoid the above problems by adding an [http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/ConfigFiles.html#//apple_ref/doc/uid/20002091-SW1 __info_plist section] to your Mach-O executable. If you succeed, please post to the VTK list.<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.3 and older, the short answer is "no".<br />
<br />
For VTK CVS the short answer is "mostly". You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. The usual settings are:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk <br />
<br />
This will result in a Universal build. However, there may be runtime bugs due to VTK's use of TRY_RUN. Work is being done to improve this situation.<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
=== How can a user process access more than 2 GB of ram in 32-bit Windows? ===<br />
<br />
By default on Windows, the most memory that a user process can access is 2 GB, no matter how much RAM you have installed in your system. With Windows XP Professional you can make it possible for a process to use up to 3 GB of memory by doing two things:<br />
<br />
1) Modify the boot parameters in boot.ini (on my 32 bit WinXP Pro machine, it's in: "C:\boot.ini") to tell the operating system that you want user processes to have access to up to 3GB of RAM (This is a really important file, and if you don't know what you are doing, stop reading this and go back to work!). This is done by adding the /3GB flag to the line of the file that tells the boot loader where the operating system is. My boot.ini file looks like:<br />
<br />
[boot loader]<br />
timeout=30<br />
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS<br />
[operating systems]<br />
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /3GB<br />
<br />
This is a very bad file to make mistakes on, so don't - it may be very difficult to repair your computer to boot if you mess up this file. There is a nice description of this in the Microsoft article <br />
[http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx Memory Support and Windows Operating Systems].<br />
<br />
2) The other thing that you need to do is make your executable LARGEADDRESSAWARE. Assuming that you have a Windows binary that you want to try this on, you can use the 'editbin' utility that comes with Visual Studio to change the setting of one bit (the IMAGE_FILE_LARGE_ADDRESS_AWARE bit) in the image header of the executable. For a program 'prog.exe' you can make the change by<br />
<br />
editbin /LARGEADDRESSAWARE prog.exe<br />
<br />
Of course, depending on how your program handles memory you might find that it crashes when you try to use the extra memory, but that's a separate issue. If you are compiling your program with a version of Visual Studio you should be able to find the switch to make your program /LARGEADDRESSAWARE.<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes in VTK between 3.2 and 4.0 ===<br />
<br />
* 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.<br />
<br />
* 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<br />
<br />
* Added special methods to data arrays to replace methods like<br />
<br />
tc SetTCoord i x y 0<br />
<br />
or<br />
<br />
vc SetVector i vx vy vz<br />
<br />
in interpreted languages (Tcl, Python, Java). Use:<br />
<br />
tc SetTuple2 i x y<br />
<br />
or<br />
<br />
vc SetTuple3 i vx vy vz<br />
<br />
* 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.<br />
<br />
* vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.<br />
<br />
* 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.<br />
<br />
* 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).<br />
<br />
* The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.<br />
<br />
* Support for reading and writing PGM and JPEG images has been included.<br />
<br />
* 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.<br />
<br />
* 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 Imaging 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.<br />
<br />
* 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.<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* 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.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* 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.<br />
<br />
* 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:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== How do I upgrade my existing C++ code from 3.2 to 4.x? ===<br />
<br />
This is (a corrected version of) an email that was posted to vtkusers.<br />
Please feel free to correct or add anything.<br />
<br />
{| cellspacing="3" <br />
|- valign="top"<br />
|width="55%" bgcolor="#f0f0ff" style="border:1px solid #ffc9c9;padding:1em;padding-top:0.5em;"|<br />
<br />
I've just ported my medium-sized (40K lines) application from vtk3.2 to<br />
vtk4.x. I thought I would share my experiences with you, in case there<br />
were people out there contemplating it but a bit scared.<br />
<br />
One source of information for upgrading code is:<br />
<br />
http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the<br />
script in the zip file.<br />
<br />
So,<br />
<br />
I switched all my include directories to the new VTK ones and<br />
recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and<br />
vtkTCoords which have both been removed. Where I was using single value<br />
scalars, like this:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetNumberOfScalars(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetScalar(i,2.3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *scalars = vtkFloatArray::New();<br />
scalars->SetNumberOfComponents(1);<br />
scalars->SetNumberOfTuples(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetTuple1(i,2.3);<br />
...<br />
<br />
OK so far, far fewer errors.<br />
<br />
Where I had 2D texture coordinates:<br />
<br />
vtkTCoords *tcoords = vtkTCoords::New();<br />
tcoords->SetNumberOfTCoords(N);<br />
...<br />
float p[3];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTCoord(i,p);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *tcoords = vtkFloatArray::New();<br />
tcoords->SetNumberOfComponents(2);<br />
tcoords->SetNumberOfTuples(N);<br />
...<br />
float p[2];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTuple(i,p);<br />
....<br />
<br />
All well and good, still fewer errors. Make sure you call<br />
SetNumberOfComponents *before* SetNumberOfTuples else you'll get<br />
problems (I did!).<br />
<br />
Where I was creating 0-255 image data and had been using:<br />
<br />
vtkScalars* scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
...<br />
<br />
Going well!<br />
<br />
When creating RGB images, I had been using:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfScalars(X*Y);<br />
...<br />
scalars->SetActiveComponent(0);<br />
scalars->SetScalar(i,val1);<br />
scalars->SetActiveComponent(1);<br />
scalars->SetScalar(i,val2);<br />
scalars->SetActiveComponent(2);<br />
scalars->SetScalar(i,val3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfTuples(X*Y);<br />
...<br />
scalars->SetComponent(i,0,val1);<br />
scalars->SetComponent(i,1,val2);<br />
scalars->SetComponent(i,2,val3);<br />
...<br />
<br />
My remaining errors concerned vtkWin32OffscreenRenderWindow that has<br />
been removed. Where I had been using:<br />
<br />
vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New();<br />
offscreen->SetOffScreenRendering(1);<br />
...<br />
<br />
All done. I'd had to throw in some #include "vtkFloatArray.h" and things<br />
like that of course. Zero compile errors.<br />
<br />
Had to remember to link against the new vtk lib files, so I removed<br />
<br />
vtkdll.lib <br />
<br />
and added<br />
<br />
vtkCommon.lib<br />
vtkGraphics.lib<br />
<br />
etc.<br />
<br />
Zero link errors. My program is up and running again, no apparant<br />
problems. Plus now I can use all the new features of vtk4. (And I'm sure<br />
it's faster but maybe that's my imagination.)<br />
<br />
All this took me about three hours.<br />
<br />
Bye!<br />
<br />
Tim.<br />
|}<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was releaseed in February 2003. VTK 4.4 (which is an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, and 5.0.3 in March 2007.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# 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.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* 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.<br />
#* 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.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* 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.<br />
* 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).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* 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. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* 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.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
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.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== Using Volume Rendering in VTK ===<br />
<br />
I recently updated my VTK CVS version. And my c++ code that use to work fine are now complaining about:<br />
<br />
undefined reference to `vtkUnstructuredGridAlgorithm::SetInput(vtkDataObject*)'<br />
undefined reference to `vtkUnstructuredGridAlgorithm::GetOutput()' <br />
<br />
There is now a new subfolder and a new option to enable building the VolumeRendering library. You have to turn VTK_USE_VOLUMERENDERING to ON in order to use it. Also make sure that your executable is linking properly to this new library:<br />
<br />
ADD_EXECUTABLE(foo foo.cxx)<br />
TARGET_LINK_LIBRARIES(foo vtkVolumeRendering)<br />
<br />
== OpenGL requirements ==<br />
<br />
=== Terminology ===<br />
<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
<br />
==== Linux/Unix ====<br />
<br />
Two ways:<br />
<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
<br />
* vendor specific tool<br />
<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or<br />
hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
== Miscellaneous questions ==<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. We think it's pretty reasonable. We do restrict the<br />
distribution of modified code. This is primarily a revision control<br />
issue. We don't want a bunch of renegade vtks running around without us<br />
having some idea why the changes were made and giving us a chance to<br />
incorporate them into the general release.<br />
<br />
The text of the VTK copyright is available [http://www.vtk.org/copyright.php here].<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
=== What is the deal with the patents ===<br />
<br />
As the copyright mentions there are some patents used in VTK. If you use<br />
any code in the Patented/ directory for commercial application you<br />
should contact the patent holder and obtain a license.<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by General Electric Company: vtkDecimate, vtkMarchingCubes,<br />
vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface.<br />
The GE contact is:<br />
<br />
Carl B. Horton<br />
Sr. Counsel, Intellectual Property<br />
3000 N. Grandview Blvd., W-710<br />
Waukesha, WI 53188<br />
Phone: (262) 513-4022<br />
E-Mail: mailto:Carl.Horton@med.ge.com<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by Kitware, Inc.: vtkGridSynchronizedTemplates3D,<br />
vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and<br />
vtkSynchronizedTemplates3D. The Kitware contact is:<br />
<br />
Ken Martin<br />
Kitware<br />
28 Corporate Drive, Suite 204,<br />
Clifton Park, NY 12065<br />
Phone:1-518-371-3971<br />
E-Mail: mailto:kitware@kitware.com<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=10881VTK/FAQ2007-11-20T16:55:54Z<p>Seanmcbride: /* How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? */</p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk is 5.0.3. This release is available at:<br />
<br />
http://www.vtk.org/files/release/5.0/<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly/<br />
<br />
See http://www.vtk.org/get-software.php for more information.<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesisitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Can I contribute money? ===<br />
<br />
Please don't send money. Not that we think you're going to send in<br />
unsolicited money. But if you were thinking about it, stop. It would<br />
just complicate our lives and make for all sorts of tax problems.<br />
<br />
(Note: if you are a company or funding institution, and would like to fund<br />
features or development, please contact Kitware http://www.kitware.com .)<br />
<br />
=== Is there a mailing list or Usenet newsgroup for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
There is also a newsgroup that mirrors the mailinglist. At this point it<br />
seems that mirror is down. Mail to the mailinglist used to be posted the<br />
newsgroup, but posts on the newsgroup were not sent to the mailinglist.<br />
The newsgroup was located at:<br />
news://scully.esat.kuleuven.ac.be/vtk.mailinglist<br />
<br />
http://www.gmane.org is a bidirectional mail-to-news gateway that carries the vtkusers mailing list. Its located here: news://news.gmane.org/gmane.comp.lib.vtk.user or here: http://news.gmane.org/gmane.comp.lib.vtk.user. vtkusers mails have been archived since April 2002 and they never expire. You can read and send mails to the vtkusers list but sent mail will bounce back without having subscribed to the list first.<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://public.kitware.com/dashboard.php?name=vtk<br />
<br />
VTK uses Dart to perform builds, run tests, and generate dashboards. You<br />
can find more information about Dart at: http://public.kitware.com/Dart/<br />
<br />
You can help improve the quality of VTK by supplying the authors with<br />
Tcl scripts that can be used as or turned into regression tests. A good<br />
regression test will:<br />
<br />
# Cover code that is not already covered.<br />
# Illustrate a bug that is occuring now or that has occurred in the past.<br />
# Use data that is on the 2nd Edition book CDROM or use "small" data files or use no data at all.<br />
# Optionally, produce an interesting result. <br />
<br />
Currently almost all regression tests are written in Tcl.<br />
<br />
Please send your Tcl regression tests to:<br />
mailto:wlorens1@mail.nycap.rr.com<br />
<br />
Bill will evaluate them for applicability and integrate them into the<br />
nightly test process.<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are five things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and work through the examples (there are 400-500 examples). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled "How to ask questions the smart<br />
way". Read it here:<br />
<br />
http://www.catb.org/~esr/faqs/smart-questions.html<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Avoid HTML emails.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
bacause the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Developement]]<br />
<br />
=== Accessing VTK CVS from behind a firewall ===<br />
<br />
Use the sourceforge project:<br />
<br />
http://cvsgrab.sourceforge.net/<br />
<br />
Just download the script and type something like:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xx<br />
<br />
(Thanks to Ingo H. de Boer)<br />
<br />
Also cvsgrab support the following option to access a particular branch:<br />
<br />
-tag <version tag> [optional] The version tag of the files to download<br />
<br />
For example to get the latest 4.4 branch:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xxx<br />
-tag release-4-4<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# 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.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
http://www.google.com/url?sa=D&q=http%3A%2F%2Fpublic.kitware.com%2Fpipermail%2Fvtkusers%2F2003-October%2F070054.html<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# 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''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
For a more elaborate DICOM library that supports compressed jpeg, you might try [http://www.creatis.insa-lyon.fr/Public/Gdcm/ Gdcm].<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
1) Using ReleaseDataFlag<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
2) Use ImmediateModeRendering<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
3) Use triangle strips via vtkStripper.<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
4) Use a different filter or mapper<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use STL. However, the following policy<br />
applies.<br />
<br />
# 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.<br />
# 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.<br />
# Include the VTK wrapper header files: vtkstd/map instead of map.<br />
# Use the vtkstd:: namespace to refer to STL classes and functions.<br />
<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| MPEG2 || || vtkMPEG2Writer<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows and Mac workstations.<br />
<br />
=== What Graphics Cards work with VTK ===<br />
<br />
VTK uses OpenGL to perform almost all of its rendering and some graphics cards/drivers have better support for OpenGL than others. This is not a listing of what cards perform well. It is a listing of what cards actually produce correct results. Here is a list of cards and their status roughly in best to worst order.<br />
<br />
* Any Nvidia desktop card on Windows -- 100% compatible<br /> <br />
* Any ATI desktop cards on Windows -- 100% compatible<br /><br />
* Mesa -- most releases pass all VTK tests<br /><br />
* Microsoft Software OpenGL -- passes all VTK tests but does have a couple bugs<br /><br />
* Mac graphics cards -- these usually pass all VTK tests. Older cards may have some issues, for example, the ATI Rage 128 Pro does not support textures larger than 1024x1024.<br /><br />
* Non-linux UNIX cards (Sun HP SGI) -- These generally work<br /><br />
* Any Nvidia card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Any ATI card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Nvidia laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests<br /><br />
* ATI laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests (e.g. [http://public.kitware.com/pipermail/vtkusers/2004-August/075966.html ATI Mobility Radeon 9600])<br /><br />
* Intel Extreme Graphics -- fails some VTK tests<br /><br />
<br />
=== How do I build the examples on the PC running Windows? ===<br />
<br />
Since building the C++ examples on the PC isn't all that easy, here are<br />
some instructions from Jack McInerney.<br />
<br />
Steps for creating a VTK C++ project 8/14/96<br />
<br />
This is based on what I learned creating a project to run the Mace<br />
example. These steps allowed me to successfully built and run this example.<br />
<br />
# Create a console project (File, New, then select Console application).<br />
# Add the files of interest to the project. (e.g., Mace.cxx)<br />
# Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies<br /> 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<br />
# 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).<br />
# 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 <br /> This is a self extracting archive which contains these files. Simply place them in your windows system directory.<br />
# Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless<br /><br />
<br />
When you go to run the program, it will bomb out unless it can find 2<br />
DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the<br />
project directory or the C:\WINDOWS directory. These files are supplied<br />
on the vtk CD-ROM (in the vtk\bin directory).<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
vtk builds on 64 bit systems, that is, systems where sizeof(void*) is 64 bits. However, parts of the vtk codebase are not 64 bit clean and so runtime problems are likely if that code is used.<br />
<br />
===== General =====<br />
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.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work reasonably with 64 bit Cocoa.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== What size swap space should I use on a PC? ===<br />
<br />
Building vtk on the PC requires a significant amount of memory (at least<br />
when using Visual C++)... but the final product is nice and compact. To<br />
build vtk on the PC, we recommend setting the min/max swap space to at<br />
least 400MB/500MB (depending on how much RAM you have... the sum of RAM<br />
and swap space should be roughly 500+ MB).<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
Struggled a few hours to get VTK to do offscreen rendering. I use it to<br />
batch process medical images. Without actually producing output on the<br />
screen, I still print resulting images in a report to easily review the<br />
results of an experiment.<br />
<br />
Here is how I solved this problem for VTK version 4.2.2.<br />
<br />
1. Download Mesa-4.0.4 source<br />
<br />
Modify Mesa-4.0.4/Make-config in the 'linux:' target the following vars:<br />
<br />
GL_LIB = libVTKMesaGL.so<br />
GLU_LIB = libVTKMesaGLU.so<br />
GLUT_LIB = libVTKMesaglut.so<br />
GLW_LIB = libVTKMesaGLw.so<br />
OSMESA_LIB = libOSVTKMesa.so<br />
<br />
In Mesa 6.2.1 you need to edit Mesa/configs/default instead:<br />
<br />
# Library names (base name)<br />
GL_LIB = VTKMesaGL<br />
GLU_LIB = VTKMesaGLU<br />
GLUT_LIB = VTKMesaglut<br />
GLW_LIB = VTKMesaGLw<br />
OSMESA_LIB = VTKMesaOSMesa<br />
<br />
<br />
And then export this env var:<br />
<br />
export 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"<br />
<br />
then<br />
<br />
For Mesa 4.0.4<br />
<br />
make -f Makefile.X11 linux <br />
cp Mesa-4.0.4/lib/* /data/usr/mesa404/lib/<br />
<br />
in Mesa 6.2.1:<br />
<br />
make linux-x86<br />
make install<br />
(I generally use /opt/VTKMesa/*)<br />
<br />
I use 'VTKMesa' name extension to avoid conflicts with my RH9.0 libs<br />
(especially OSMesa lib in XFree!). I'm using shared libraries, because<br />
that allows me to use dynamic libs from VTK and not the vtk program<br />
itself without explicitly having to load VTKMesaGL with my app. I copied<br />
the 'VTKMesa' libs in /data/usr/mesa404/lib/, but any odd place probably<br />
will work. Avoid /usr/lib /usr/local/lib for now.<br />
<br />
2. Follow normal instructions to get a proper working vtk, then<br />
<br />
ccmake <br />
<br />
with the following options:<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
| VTK_USE_MANGLED_MESA || ON<br />
|-<br />
| MANGLED_MESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_MESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaGL.so<br />
|-<br />
| MANGLED_OSMESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_OSMESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaOSMesa.so<br />
|-<br />
| OPENGL_xmesa_INCLUDE_DIR || /data/usr/mesa404/include<br />
|}<br />
<br />
test using /data/prog/VTK-4.2.2/Examples/MangledMesa/Tcl scripts<br />
<br />
<br />
If you're doing things on UNIX, you should also look at [[VTK Classes]]. It has links to RenderWindow objects that are probably easier to use than rebuilding VTK with Mesa.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
On Mac OS X, there are (at least) two kinds of executables:<br />
* [http://developer.apple.com/documentation/MacOSX/Conceptual/BPInternational/Articles/InternatSupport.html#//apple_ref/doc/uid/20000278-73764 Application Bundles]<br />
* plain UNIX executables<br />
<br />
For a program to be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction) it must be an Application Bundle. If a plain UNIX executable tries, there will be various bugs, such as keyboard and mouse events not working.<br />
<br />
Many of the example VTK applications are built as plain UNIX executables, and thus have these problems. This is [http://www.vtk.org/Bug/bug.php?op=show&bugid=2025 VTK bug 2025].<br />
<br />
When you build your own VTK application, be sure it is in the form of an Application Bundle. With CMake 2.0.5 or later, simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.3 and older, the short answer is "no".<br />
<br />
For VTK CVS the short answer is "mostly". You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. The usual settings are:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk <br />
<br />
This will result in a Universal build. However, there may be runtime bugs due to VTK's use of TRY_RUN. Work is being done to improve this situation.<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes in VTK between 3.2 and 4.0 ===<br />
<br />
* 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.<br />
<br />
* 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<br />
<br />
* Added special methods to data arrays to replace methods like<br />
<br />
tc SetTCoord i x y 0<br />
<br />
or<br />
<br />
vc SetVector i vx vy vz<br />
<br />
in interpreted languages (Tcl, Python, Java). Use:<br />
<br />
tc SetTuple2 i x y<br />
<br />
or<br />
<br />
vc SetTuple3 i vx vy vz<br />
<br />
* 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.<br />
<br />
* vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.<br />
<br />
* 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.<br />
<br />
* 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).<br />
<br />
* The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.<br />
<br />
* Support for reading and writing PGM and JPEG images has been included.<br />
<br />
* 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.<br />
<br />
* 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 Imaging 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.<br />
<br />
* 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.<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* 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.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* 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.<br />
<br />
* 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:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== How do I upgrade my existing C++ code from 3.2 to 4.x? ===<br />
<br />
This is (a corrected version of) an email that was posted to vtkusers.<br />
Please feel free to correct or add anything.<br />
<br />
{| cellspacing="3" <br />
|- valign="top"<br />
|width="55%" bgcolor="#f0f0ff" style="border:1px solid #ffc9c9;padding:1em;padding-top:0.5em;"|<br />
<br />
I've just ported my medium-sized (40K lines) application from vtk3.2 to<br />
vtk4.x. I thought I would share my experiences with you, in case there<br />
were people out there contemplating it but a bit scared.<br />
<br />
One source of information for upgrading code is:<br />
<br />
http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the<br />
script in the zip file.<br />
<br />
So,<br />
<br />
I switched all my include directories to the new VTK ones and<br />
recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and<br />
vtkTCoords which have both been removed. Where I was using single value<br />
scalars, like this:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetNumberOfScalars(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetScalar(i,2.3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *scalars = vtkFloatArray::New();<br />
scalars->SetNumberOfComponents(1);<br />
scalars->SetNumberOfTuples(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetTuple1(i,2.3);<br />
...<br />
<br />
OK so far, far fewer errors.<br />
<br />
Where I had 2D texture coordinates:<br />
<br />
vtkTCoords *tcoords = vtkTCoords::New();<br />
tcoords->SetNumberOfTCoords(N);<br />
...<br />
float p[3];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTCoord(i,p);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *tcoords = vtkFloatArray::New();<br />
tcoords->SetNumberOfComponents(2);<br />
tcoords->SetNumberOfTuples(N);<br />
...<br />
float p[2];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTuple(i,p);<br />
....<br />
<br />
All well and good, still fewer errors. Make sure you call<br />
SetNumberOfComponents *before* SetNumberOfTuples else you'll get<br />
problems (I did!).<br />
<br />
Where I was creating 0-255 image data and had been using:<br />
<br />
vtkScalars* scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
...<br />
<br />
Going well!<br />
<br />
When creating RGB images, I had been using:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfScalars(X*Y);<br />
...<br />
scalars->SetActiveComponent(0);<br />
scalars->SetScalar(i,val1);<br />
scalars->SetActiveComponent(1);<br />
scalars->SetScalar(i,val2);<br />
scalars->SetActiveComponent(2);<br />
scalars->SetScalar(i,val3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfTuples(X*Y);<br />
...<br />
scalars->SetComponent(i,0,val1);<br />
scalars->SetComponent(i,1,val2);<br />
scalars->SetComponent(i,2,val3);<br />
...<br />
<br />
My remaining errors concerned vtkWin32OffscreenRenderWindow that has<br />
been removed. Where I had been using:<br />
<br />
vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New();<br />
offscreen->SetOffScreenRendering(1);<br />
...<br />
<br />
All done. I'd had to throw in some #include "vtkFloatArray.h" and things<br />
like that of course. Zero compile errors.<br />
<br />
Had to remember to link against the new vtk lib files, so I removed<br />
<br />
vtkdll.lib <br />
<br />
and added<br />
<br />
vtkCommon.lib<br />
vtkGraphics.lib<br />
<br />
etc.<br />
<br />
Zero link errors. My program is up and running again, no apparant<br />
problems. Plus now I can use all the new features of vtk4. (And I'm sure<br />
it's faster but maybe that's my imagination.)<br />
<br />
All this took me about three hours.<br />
<br />
Bye!<br />
<br />
Tim.<br />
|}<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was releaseed in February 2003. VTK 4.4 (which is an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, and 5.0.3 in March 2007.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# 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.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* 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.<br />
#* 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.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* 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.<br />
* 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).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* 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. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* 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.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
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.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== Using Volume Rendering in VTK ===<br />
<br />
I recently updated my VTK CVS version. And my c++ code that use to work fine are now complaining about:<br />
<br />
undefined reference to `vtkUnstructuredGridAlgorithm::SetInput(vtkDataObject*)'<br />
undefined reference to `vtkUnstructuredGridAlgorithm::GetOutput()' <br />
<br />
There is now a new subfolder and a new option to enable building the VolumeRendering library. You have to turn VTK_USE_VOLUMERENDERING to ON in order to use it. Also make sure that your executable is linking properly to this new library:<br />
<br />
ADD_EXECUTABLE(foo foo.cxx)<br />
TARGET_LINK_LIBRARIES(foo vtkVolumeRendering)<br />
<br />
== OpenGL requirements ==<br />
<br />
=== Terminology ===<br />
<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
<br />
==== Linux/Unix ====<br />
<br />
Two ways:<br />
<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
<br />
* vendor specific tool<br />
<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or<br />
hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
== Miscellaneous questions ==<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. We think it's pretty reasonable. We do restrict the<br />
distribution of modified code. This is primarily a revision control<br />
issue. We don't want a bunch of renegade vtks running around without us<br />
having some idea why the changes were made and giving us a chance to<br />
incorporate them into the general release.<br />
<br />
The text of the VTK copyright is available [http://www.vtk.org/copyright.php here].<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
=== What is the deal with the patents ===<br />
<br />
As the copyright mentions there are some patents used in VTK. If you use<br />
any code in the Patented/ directory for commercial application you<br />
should contact the patent holder and obtain a license.<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by General Electric Company: vtkDecimate, vtkMarchingCubes,<br />
vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface.<br />
The GE contact is:<br />
<br />
Carl B. Horton<br />
Sr. Counsel, Intellectual Property<br />
3000 N. Grandview Blvd., W-710<br />
Waukesha, WI 53188<br />
Phone: (262) 513-4022<br />
E-Mail: mailto:Carl.Horton@med.ge.com<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by Kitware, Inc.: vtkGridSynchronizedTemplates3D,<br />
vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and<br />
vtkSynchronizedTemplates3D. The Kitware contact is:<br />
<br />
Ken Martin<br />
Kitware<br />
28 Corporate Drive, Suite 204,<br />
Clifton Park, NY 12065<br />
Phone:1-518-371-3971<br />
E-Mail: mailto:kitware@kitware.com<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbridehttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=10880VTK/FAQ2007-11-20T16:48:43Z<p>Seanmcbride: /* 64-bit System Issues */</p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk is 5.0.3. This release is available at:<br />
<br />
http://www.vtk.org/files/release/5.0/<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly/<br />
<br />
See http://www.vtk.org/get-software.php for more information.<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesisitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Can I contribute money? ===<br />
<br />
Please don't send money. Not that we think you're going to send in<br />
unsolicited money. But if you were thinking about it, stop. It would<br />
just complicate our lives and make for all sorts of tax problems.<br />
<br />
(Note: if you are a company or funding institution, and would like to fund<br />
features or development, please contact Kitware http://www.kitware.com .)<br />
<br />
=== Is there a mailing list or Usenet newsgroup for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
There is also a newsgroup that mirrors the mailinglist. At this point it<br />
seems that mirror is down. Mail to the mailinglist used to be posted the<br />
newsgroup, but posts on the newsgroup were not sent to the mailinglist.<br />
The newsgroup was located at:<br />
news://scully.esat.kuleuven.ac.be/vtk.mailinglist<br />
<br />
http://www.gmane.org is a bidirectional mail-to-news gateway that carries the vtkusers mailing list. Its located here: news://news.gmane.org/gmane.comp.lib.vtk.user or here: http://news.gmane.org/gmane.comp.lib.vtk.user. vtkusers mails have been archived since April 2002 and they never expire. You can read and send mails to the vtkusers list but sent mail will bounce back without having subscribed to the list first.<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://public.kitware.com/dashboard.php?name=vtk<br />
<br />
VTK uses Dart to perform builds, run tests, and generate dashboards. You<br />
can find more information about Dart at: http://public.kitware.com/Dart/<br />
<br />
You can help improve the quality of VTK by supplying the authors with<br />
Tcl scripts that can be used as or turned into regression tests. A good<br />
regression test will:<br />
<br />
# Cover code that is not already covered.<br />
# Illustrate a bug that is occuring now or that has occurred in the past.<br />
# Use data that is on the 2nd Edition book CDROM or use "small" data files or use no data at all.<br />
# Optionally, produce an interesting result. <br />
<br />
Currently almost all regression tests are written in Tcl.<br />
<br />
Please send your Tcl regression tests to:<br />
mailto:wlorens1@mail.nycap.rr.com<br />
<br />
Bill will evaluate them for applicability and integrate them into the<br />
nightly test process.<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are five things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and work through the examples (there are 400-500 examples). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled "How to ask questions the smart<br />
way". Read it here:<br />
<br />
http://www.catb.org/~esr/faqs/smart-questions.html<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Avoid HTML emails.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
bacause the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Developement]]<br />
<br />
=== Accessing VTK CVS from behind a firewall ===<br />
<br />
Use the sourceforge project:<br />
<br />
http://cvsgrab.sourceforge.net/<br />
<br />
Just download the script and type something like:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xx<br />
<br />
(Thanks to Ingo H. de Boer)<br />
<br />
Also cvsgrab support the following option to access a particular branch:<br />
<br />
-tag <version tag> [optional] The version tag of the files to download<br />
<br />
For example to get the latest 4.4 branch:<br />
<br />
cvsgrab -rootUrl http://public.kitware.com/cgi-bin/cvsweb.cgi/ -packagePath VTK -destDir . <br />
-proxyUser xxx -proxyPassword xxx -proxyHost xxx -proxyPort xxx<br />
-tag release-4-4<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# 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.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
http://www.google.com/url?sa=D&q=http%3A%2F%2Fpublic.kitware.com%2Fpipermail%2Fvtkusers%2F2003-October%2F070054.html<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# 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''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
For a more elaborate DICOM library that supports compressed jpeg, you might try [http://www.creatis.insa-lyon.fr/Public/Gdcm/ Gdcm].<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
1) Using ReleaseDataFlag<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
2) Use ImmediateModeRendering<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
3) Use triangle strips via vtkStripper.<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
4) Use a different filter or mapper<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use STL. However, the following policy<br />
applies.<br />
<br />
# 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.<br />
# 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.<br />
# Include the VTK wrapper header files: vtkstd/map instead of map.<br />
# Use the vtkstd:: namespace to refer to STL classes and functions.<br />
<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| MPEG2 || || vtkMPEG2Writer<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows and Mac workstations.<br />
<br />
=== What Graphics Cards work with VTK ===<br />
<br />
VTK uses OpenGL to perform almost all of its rendering and some graphics cards/drivers have better support for OpenGL than others. This is not a listing of what cards perform well. It is a listing of what cards actually produce correct results. Here is a list of cards and their status roughly in best to worst order.<br />
<br />
* Any Nvidia desktop card on Windows -- 100% compatible<br /> <br />
* Any ATI desktop cards on Windows -- 100% compatible<br /><br />
* Mesa -- most releases pass all VTK tests<br /><br />
* Microsoft Software OpenGL -- passes all VTK tests but does have a couple bugs<br /><br />
* Mac graphics cards -- these usually pass all VTK tests. Older cards may have some issues, for example, the ATI Rage 128 Pro does not support textures larger than 1024x1024.<br /><br />
* Non-linux UNIX cards (Sun HP SGI) -- These generally work<br /><br />
* Any Nvidia card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Any ATI card under linux -- these usually pass all VTK tests but have some issues<br /><br />
* Nvidia laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests<br /><br />
* ATI laptop graphics cards under Windows -- known to have some issues, newer cards pass all tests (e.g. [http://public.kitware.com/pipermail/vtkusers/2004-August/075966.html ATI Mobility Radeon 9600])<br /><br />
* Intel Extreme Graphics -- fails some VTK tests<br /><br />
<br />
=== How do I build the examples on the PC running Windows? ===<br />
<br />
Since building the C++ examples on the PC isn't all that easy, here are<br />
some instructions from Jack McInerney.<br />
<br />
Steps for creating a VTK C++ project 8/14/96<br />
<br />
This is based on what I learned creating a project to run the Mace<br />
example. These steps allowed me to successfully built and run this example.<br />
<br />
# Create a console project (File, New, then select Console application).<br />
# Add the files of interest to the project. (e.g., Mace.cxx)<br />
# Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies<br /> 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<br />
# 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).<br />
# 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 <br /> This is a self extracting archive which contains these files. Simply place them in your windows system directory.<br />
# Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless<br /><br />
<br />
When you go to run the program, it will bomb out unless it can find 2<br />
DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the<br />
project directory or the C:\WINDOWS directory. These files are supplied<br />
on the vtk CD-ROM (in the vtk\bin directory).<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
vtk builds on 64 bit systems, that is, systems where sizeof(void*) is 64 bits. However, parts of the vtk codebase are not 64 bit clean and so runtime problems are likely if that code is used.<br />
<br />
===== General =====<br />
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.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work reasonably with 64 bit Cocoa.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== What size swap space should I use on a PC? ===<br />
<br />
Building vtk on the PC requires a significant amount of memory (at least<br />
when using Visual C++)... but the final product is nice and compact. To<br />
build vtk on the PC, we recommend setting the min/max swap space to at<br />
least 400MB/500MB (depending on how much RAM you have... the sum of RAM<br />
and swap space should be roughly 500+ MB).<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
Struggled a few hours to get VTK to do offscreen rendering. I use it to<br />
batch process medical images. Without actually producing output on the<br />
screen, I still print resulting images in a report to easily review the<br />
results of an experiment.<br />
<br />
Here is how I solved this problem for VTK version 4.2.2.<br />
<br />
1. Download Mesa-4.0.4 source<br />
<br />
Modify Mesa-4.0.4/Make-config in the 'linux:' target the following vars:<br />
<br />
GL_LIB = libVTKMesaGL.so<br />
GLU_LIB = libVTKMesaGLU.so<br />
GLUT_LIB = libVTKMesaglut.so<br />
GLW_LIB = libVTKMesaGLw.so<br />
OSMESA_LIB = libOSVTKMesa.so<br />
<br />
In Mesa 6.2.1 you need to edit Mesa/configs/default instead:<br />
<br />
# Library names (base name)<br />
GL_LIB = VTKMesaGL<br />
GLU_LIB = VTKMesaGLU<br />
GLUT_LIB = VTKMesaglut<br />
GLW_LIB = VTKMesaGLw<br />
OSMESA_LIB = VTKMesaOSMesa<br />
<br />
<br />
And then export this env var:<br />
<br />
export 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"<br />
<br />
then<br />
<br />
For Mesa 4.0.4<br />
<br />
make -f Makefile.X11 linux <br />
cp Mesa-4.0.4/lib/* /data/usr/mesa404/lib/<br />
<br />
in Mesa 6.2.1:<br />
<br />
make linux-x86<br />
make install<br />
(I generally use /opt/VTKMesa/*)<br />
<br />
I use 'VTKMesa' name extension to avoid conflicts with my RH9.0 libs<br />
(especially OSMesa lib in XFree!). I'm using shared libraries, because<br />
that allows me to use dynamic libs from VTK and not the vtk program<br />
itself without explicitly having to load VTKMesaGL with my app. I copied<br />
the 'VTKMesa' libs in /data/usr/mesa404/lib/, but any odd place probably<br />
will work. Avoid /usr/lib /usr/local/lib for now.<br />
<br />
2. Follow normal instructions to get a proper working vtk, then<br />
<br />
ccmake <br />
<br />
with the following options:<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
| VTK_USE_MANGLED_MESA || ON<br />
|-<br />
| MANGLED_MESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_MESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaGL.so<br />
|-<br />
| MANGLED_OSMESA_INCLUDE_DIR || /data/usr/mesa404/include<br />
|-<br />
| MANGLED_OSMESA_LIBRARY || /data/usr/mesa404/lib/libVTKMesaOSMesa.so<br />
|-<br />
| OPENGL_xmesa_INCLUDE_DIR || /data/usr/mesa404/include<br />
|}<br />
<br />
test using /data/prog/VTK-4.2.2/Examples/MangledMesa/Tcl scripts<br />
<br />
<br />
If you're doing things on UNIX, you should also look at [[VTK Classes]]. It has links to RenderWindow objects that are probably easier to use than rebuilding VTK with Mesa.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
On Mac OS X, there are (at least) two kinds of executables:<br />
* [http://developer.apple.com/documentation/MacOSX/Conceptual/BPInternational/Articles/InternatSupport.html#//apple_ref/doc/uid/20000278-73764 Application Bundles]<br />
* plain UNIX executables<br />
<br />
For a program to be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction) it must be an Application Bundle. If a plain UNIX executable tries, there will be various bugs, such as keyboard and mouse events not working.<br />
<br />
Many of the example VTK applications are built as plain UNIX executables, and thus have these problems. This is [http://www.vtk.org/Bug/bug.php?op=show&bugid=2025 VTK bug 2025].<br />
<br />
When you build your own VTK application, be sure it is in the form of an Application Bundle. With CMake 2.0.5 or later, simply add the following to your CMakeLists.txt file:<br />
<br />
IF(APPLE)<br />
SET(EXECUTABLE_FLAG MACOSX_BUNDLE)<br />
ENDIF(APPLE)<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.3 and older, the short answer is "no".<br />
<br />
For VTK CVS the short answer is "mostly". You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. The usual settings are:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk <br />
<br />
This will result in a Universal build. However, there may be runtime bugs due to VTK's use of TRY_RUN. Work is being done to improve this situation.<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes in VTK between 3.2 and 4.0 ===<br />
<br />
* 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.<br />
<br />
* 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<br />
<br />
* Added special methods to data arrays to replace methods like<br />
<br />
tc SetTCoord i x y 0<br />
<br />
or<br />
<br />
vc SetVector i vx vy vz<br />
<br />
in interpreted languages (Tcl, Python, Java). Use:<br />
<br />
tc SetTuple2 i x y<br />
<br />
or<br />
<br />
vc SetTuple3 i vx vy vz<br />
<br />
* 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.<br />
<br />
* vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.<br />
<br />
* 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.<br />
<br />
* 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).<br />
<br />
* The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.<br />
<br />
* Support for reading and writing PGM and JPEG images has been included.<br />
<br />
* 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.<br />
<br />
* 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 Imaging 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.<br />
<br />
* 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.<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* 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.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* 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.<br />
<br />
* 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:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* 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.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== How do I upgrade my existing C++ code from 3.2 to 4.x? ===<br />
<br />
This is (a corrected version of) an email that was posted to vtkusers.<br />
Please feel free to correct or add anything.<br />
<br />
{| cellspacing="3" <br />
|- valign="top"<br />
|width="55%" bgcolor="#f0f0ff" style="border:1px solid #ffc9c9;padding:1em;padding-top:0.5em;"|<br />
<br />
I've just ported my medium-sized (40K lines) application from vtk3.2 to<br />
vtk4.x. I thought I would share my experiences with you, in case there<br />
were people out there contemplating it but a bit scared.<br />
<br />
One source of information for upgrading code is:<br />
<br />
http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the<br />
script in the zip file.<br />
<br />
So,<br />
<br />
I switched all my include directories to the new VTK ones and<br />
recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and<br />
vtkTCoords which have both been removed. Where I was using single value<br />
scalars, like this:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetNumberOfScalars(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetScalar(i,2.3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *scalars = vtkFloatArray::New();<br />
scalars->SetNumberOfComponents(1);<br />
scalars->SetNumberOfTuples(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetTuple1(i,2.3);<br />
...<br />
<br />
OK so far, far fewer errors.<br />
<br />
Where I had 2D texture coordinates:<br />
<br />
vtkTCoords *tcoords = vtkTCoords::New();<br />
tcoords->SetNumberOfTCoords(N);<br />
...<br />
float p[3];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTCoord(i,p);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *tcoords = vtkFloatArray::New();<br />
tcoords->SetNumberOfComponents(2);<br />
tcoords->SetNumberOfTuples(N);<br />
...<br />
float p[2];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTuple(i,p);<br />
....<br />
<br />
All well and good, still fewer errors. Make sure you call<br />
SetNumberOfComponents *before* SetNumberOfTuples else you'll get<br />
problems (I did!).<br />
<br />
Where I was creating 0-255 image data and had been using:<br />
<br />
vtkScalars* scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
...<br />
<br />
Going well!<br />
<br />
When creating RGB images, I had been using:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfScalars(X*Y);<br />
...<br />
scalars->SetActiveComponent(0);<br />
scalars->SetScalar(i,val1);<br />
scalars->SetActiveComponent(1);<br />
scalars->SetScalar(i,val2);<br />
scalars->SetActiveComponent(2);<br />
scalars->SetScalar(i,val3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfTuples(X*Y);<br />
...<br />
scalars->SetComponent(i,0,val1);<br />
scalars->SetComponent(i,1,val2);<br />
scalars->SetComponent(i,2,val3);<br />
...<br />
<br />
My remaining errors concerned vtkWin32OffscreenRenderWindow that has<br />
been removed. Where I had been using:<br />
<br />
vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New();<br />
offscreen->SetOffScreenRendering(1);<br />
...<br />
<br />
All done. I'd had to throw in some #include "vtkFloatArray.h" and things<br />
like that of course. Zero compile errors.<br />
<br />
Had to remember to link against the new vtk lib files, so I removed<br />
<br />
vtkdll.lib <br />
<br />
and added<br />
<br />
vtkCommon.lib<br />
vtkGraphics.lib<br />
<br />
etc.<br />
<br />
Zero link errors. My program is up and running again, no apparant<br />
problems. Plus now I can use all the new features of vtk4. (And I'm sure<br />
it's faster but maybe that's my imagination.)<br />
<br />
All this took me about three hours.<br />
<br />
Bye!<br />
<br />
Tim.<br />
|}<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was releaseed in February 2003. VTK 4.4 (which is an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, and 5.0.3 in March 2007.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# 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.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* 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.<br />
#* 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.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* 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.<br />
* 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).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* 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. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* 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.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
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.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== Using Volume Rendering in VTK ===<br />
<br />
I recently updated my VTK CVS version. And my c++ code that use to work fine are now complaining about:<br />
<br />
undefined reference to `vtkUnstructuredGridAlgorithm::SetInput(vtkDataObject*)'<br />
undefined reference to `vtkUnstructuredGridAlgorithm::GetOutput()' <br />
<br />
There is now a new subfolder and a new option to enable building the VolumeRendering library. You have to turn VTK_USE_VOLUMERENDERING to ON in order to use it. Also make sure that your executable is linking properly to this new library:<br />
<br />
ADD_EXECUTABLE(foo foo.cxx)<br />
TARGET_LINK_LIBRARIES(foo vtkVolumeRendering)<br />
<br />
== OpenGL requirements ==<br />
<br />
=== Terminology ===<br />
<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
<br />
==== Linux/Unix ====<br />
<br />
Two ways:<br />
<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
<br />
* vendor specific tool<br />
<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac ====<br />
<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or<br />
hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
== Miscellaneous questions ==<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. We think it's pretty reasonable. We do restrict the<br />
distribution of modified code. This is primarily a revision control<br />
issue. We don't want a bunch of renegade vtks running around without us<br />
having some idea why the changes were made and giving us a chance to<br />
incorporate them into the general release.<br />
<br />
The text of the VTK copyright is available [http://www.vtk.org/copyright.php here].<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
=== What is the deal with the patents ===<br />
<br />
As the copyright mentions there are some patents used in VTK. If you use<br />
any code in the Patented/ directory for commercial application you<br />
should contact the patent holder and obtain a license.<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by General Electric Company: vtkDecimate, vtkMarchingCubes,<br />
vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface.<br />
The GE contact is:<br />
<br />
Carl B. Horton<br />
Sr. Counsel, Intellectual Property<br />
3000 N. Grandview Blvd., W-710<br />
Waukesha, WI 53188<br />
Phone: (262) 513-4022<br />
E-Mail: mailto:Carl.Horton@med.ge.com<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by Kitware, Inc.: vtkGridSynchronizedTemplates3D,<br />
vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and<br />
vtkSynchronizedTemplates3D. The Kitware contact is:<br />
<br />
Ken Martin<br />
Kitware<br />
28 Corporate Drive, Suite 204,<br />
Clifton Park, NY 12065<br />
Phone:1-518-371-3971<br />
E-Mail: mailto:kitware@kitware.com<br />
<br />
{{VTK/Template/Footer}}</div>Seanmcbride