Ecosyste.ms: Awesome

Last synced: 3 days ago JSON representation

VTK README

Welcome To The Visualization Toolkit

     Introduction

 Copyright Notice

 Organization

 Documentation

 Compilation

         Building with CMake

 Configuration Options in CMake

 Installation

 Common Problems

 Getting Data

 Running VTK

 Adding A New Class

 Getting Help / Mailing List

Introduction

VTK is an open-source software system for image processing, 3D graphics,

volume rendering and visualization. VTK includes many advanced algorithms

(e.g., surface reconstruction, implicit modelling, decimation) and rendering

techniques (e.g., hardware-accelerated volume rendering, LOD control).

VTK is used by academicians for teaching and research; by government research

institutions such as Los Alamos National Lab in the US or CINECA in Italy; and

by many commercial firms who use VTK to build or extend products.

The origin of VTK is with the textbook "The Visualization Toolkit, an

Object-Oriented Approach to 3D Graphics" originally published by

Prentice Hall and now published by Kitware, Inc. (Third Edition

ISBN 1-930934-07-6). VTK has grown (since its initial release in 1994)

to a world-wide user base in the commercial, academic, and research

communities.

This README is written for VTK version 5.0 and greater. For more information,

additional resources, and the FAQ see the web page at

http://www.vtk.org

Copyright Notice

VTK has a generous open-source copyright modelled after the BSD license. Yes,

you can use VTK in commercial products. The complete text of the

copyright follows.

Copyright (c) 1993-2005 Ken Martin, Will Schroeder, Bill Lorensen

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above copyright notice,

   this list of conditions and the following disclaimer.

 * Redistributions in binary form must reproduce the above copyright notice,

   this list of conditions and the following disclaimer in the documentation

   and/or other materials provided with the distribution.

 * Neither name of Ken Martin, Will Schroeder, or Bill Lorensen nor the names

   of any contributors may be used to endorse or promote products derived

   from this software without specific prior written permission.

 * Modified source versions must be plainly marked as such, and must not be

   misrepresented as being the original software.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''

AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR

ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR

SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER

CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Organization

The VTK source code repository is organized into four major sections.

The toolkit source code is found in the following directories

      next to this README.  In some cases an additional README.html

      file may be found in the named directory. Please see these for

      more information.

Common- Core classes commonly used by other kits

Filtering- Data pipeline implementation superclasses

Rendering- Classes used to render a scene (surface primitives)

Graphics- Filters that process 3D data

Imaging- Specialized image processing filters (2D & 3D)

Infovis- Classes for information visualization

IO- Classes for reading and writing data

Views- Classes for application-level views

VolumeRendering- Classes for rendering volume data

Hybrid- Complex classes that depend on imaging and graphics

Widgets- Classes for interacting with the objects in the scene

Parallel- Parallel processing support such as MPI

GenericFiltering- Part of an adaptor framework

         supporting integration of VTK with external systems

Examples that are reasonably well documented are found in the

         VTK/Examples directory. You may wish to start with the examples

         found in the Tutorial directory.

  The Utilities directory includes things like jpeg, png,

         and zlib source code. This code is used by VTK in various ways

         (reading/writing data, etc.)

  The Wrapping directory contains code related to VTK's automated

         wrapping process. The wrapping process automatically generates

         Tcl, Python, and/or Java bindings depending on how the build

         process is configured.

There are hundreds of testing examples located in the Testing/ directory

under each source code directory (e.g., Graphics/Testing). These are

undocumented tests but can be helpful in some cases.

Documentation

The ideal way to learn about the software is from two books:

The Visualization Toolkit, An Object-Oriented Approach to 3D Graphics

and The VTK User's Guide both published by Kitware, Inc. (Note:

The Visualization Toolkit was originally published by Prentice-Hall,

the third edition is published by Kitware.)

You may order the books from the following locations (Amazon.com also

carries the books.)

  The Visualization Toolkit, An Object-Oriented Approach to 3D Graphics (Third Edition)

  by Will Schroeder, Ken Martin and Bill Lorensen.

  Kitware, Inc.,

  ISBN 1-930934-07-6

  http://www.kitware.com/products/vtktextbook.html

  The VTK User's Guide (VTK 4.2 Edition)

  Kitware, Inc.,

  ISBN 1-930934-08-4

  http://www.kitware.com/products/vtkguide.html

On-line Doxygen man pages are also available at

http://www.vtk.org/doc/nightly/html/

Compilation

The Visualization Toolkit can be built on UNIX, PC (Windows

NT/2000/XP/7), and Mac OS X 10.5 Leopard (or greater) systems.  VTK uses

CMake to generate its build system.

To build VTK one must first install CMake version 2.8.5 or higher.

CMake may be downloaded from http://www.cmake.org/HTML/Download.html.

The instructions below cover the basics of running CMake for VTK under

the assumption that CMake is already installed.  See the CMake web

page for details on

  intalling and

  running CMake.

Compiling VTK requires a complete VTK source tree.  Running VTK tests

requires a complete VTK data tree.  Now is the time to extract the

source and data archives if one has not done so already.  These

instructions assume there is a directory "VTK" containing

the source code and optionally a sibling directory

"VTKData" containing the data.

Building with CMake

CMake must be run to generate a build system for VTK.  The build

system may be placed either in the VTK source tree (an

in-source build) or in a separate binary tree (an

out-of-source build).  We strongly encourage use of

out-of-source builds because they make it easy to have multiple builds

with different configurations sharing the same source tree.  Once a

single in-source build has been created it is the only build tree that

can be associated with that source tree.  A source tree may not be

used both for an in-source build and an out-of-source build, but any

number of out-of-source builds may share a source tree that does not

have an in-source build.  Having multiple out-of-source builds is

particularly useful for installing VTK on multiple architectures using

a single source tree on a shared disk.

CMake provides both a command-line tool and interactive interfaces.

Advanced users may wish to use the command-line tool but here we

document the CMake interactive interface for each platform:

Windows

      Run the CMakeSetup dialog to get started.  It must be executed

      from an environment configured to run the compiler to be used.

      In the case of the Visual Studio IDE no special environment is

      needed and CMakeSetup can be started from its icon.  In the case

      of a Visual Studio NMake, Borland C++, or MinGW build the

      CMakeSetup dialog should be executed from a command prompt with

      the appropriate environment set.

      The dialog prompts for the location of the source and binary

      trees.  There may also be prompt for the build system generator

      to be used ("Build For:").  Once these are set then CMake is

      ready for a first pass at configuring the VTK build system.  Use

      the "Configure" button to initiate this process.  If there was

      no earlier prompt for the build system generator a separate

      dialog will appear during the first configuration step to prompt

      for generator selection.  After a while the dialog will present

      a set of configuration options.

      See below for details on the meaning of

      each of these options.  After setting the options as desired

      press "Configure" again to make another pass at configuring VTK.

      New options may appear when earlier options are adjusted.  Keep

      adjusting options and pressing "Configure" until the desired

      configuration is reached.  Finally press the "Generate" button

      to actually generate the build system.

      Now that the build system has been generated the corresponding

      native tools can be used to build VTK.  In the case of the

      Visual Studio IDE simply run it and load the VTK workspace or

      solution file from the binary tree specified in the CMakeSetup

      dialog.  Select and build the ALL_BUILD target.  In

      the case of a Visual Studio NMake, Borland C++, or MinGW build

      use the corresponding make tool (nmake,

      make, and make, respectively) from the

      command line.

UNIX / Cygwin / Mac OS X

      CMake should be run from the command line on these platforms.

      The current working directory should be set to the desired

      binary tree location in which the build system should be

      generated.  One command-line argument is used to specify the

      location of the source tree.  CMake will usually choose the

      system C and C++ compilers automatically but it can be told to

      use specific compilers through the "CC" and

      "CXX" environment variables.

      A typical in-source build for VTK might look like this:

         $ ls -d VTK

         VTK/

         $ cd VTK

         $ ccmake .

         $ make

      A typical out-of-source build for VTK might look like this:

         $ ls -d VTK

         VTK/

         $ mkdir VTK-build

         $ cd VTK-build

         $ ccmake ../VTK

         $ make

      In the above examples the call to ccmake may be

      replaced by

         $ env CC=/your/c/compiler CXX=/your/C++/compiler ccmake /path/to/VTK

      in order to tell CMake to use specific C and C++ compilers.

      Setting the environment in this way will only change the

      compilers the first time CMake is run for a specific

      build tree.  Do not attempt to change the compiler of an

      existing build tree.  Instead one should create a separate build

      tree for each desired compiler.

      The ccmake tool is a curses-based dialog that may

      be used to interactively configure VTK.  When it appears press

      'c' on the keyboard to run the initial configuration of the VTK

      build system.  Eventually a set of configuration options will

      appear.  These may be edited using the arrow-keys and the ENTER

      key for navigation.  See below for

      details on the meaning of each of these options.

      Once the options have been set as desired press 'c' again to

      reconfigure.  New options may appear when earlier options are

      adjusted.  Keep adjusting options and pressing 'c' until the

      desired configuration is reached.  Finally press 'g' to actually

      generate the build system.  Now that the build system has been

      generated just run make or gmake to

      build VTK.

      NOTE: The ccmake curses dialog is the most commonly

      used interactive interface for CMake on UNIX-like platforms, so

      these instructions assume it is available.  Some system

      administrators may not have installed curses in which case

      ccmake will not be available.  On these platforms

      one may use the command "cmake -i" in place of

      ccmake and follow the on-screen instructions to

      configure VTK.  A last resort is to use the command-line

      interface to cmake, but that is beyond the scope of

      this document.  See CMake documentation for further details.

Configuration Options in CMake

VTK is a large toolkit providing a wide variety of functionality.

Several configuration options are available to customize the VTK build

system.  These options are configured through an interactive CMake

interface as described above.  Note that not

all options are available on all platforms, and some options are

available only when other options are set to a particular value.

The interactive CMake interface provides brief documentation for every

option.  Some options have more meaning than can be described in one

sentence, so additional documentation is provided here:

BUILD_SHARED_LIBS

    Sets whether the compiled VTK libraries will be shared libraries

    or static libraries.  When linking executables against static

    libraries the needed symbols will be copied from the libraries

    into the executables enabling them to run without access to the

    original libraries.  When linking executables against shared

    libraries references to the symbols are placed into the

    executables.  This has the advantage that many executables can

    share a large library without producing many copies of its code.

    Shared libraries have the disadvantage that they must be found at

    runtime in order for an executable to run.  Each operating system

    supporting shared libraries has a component known as the

    dynamic loader.  This component is responsible for finding

    the shared libraries needed by an executable when it is run.  In

    order to run VTK executables from the build tree when using shared

    libraries one may need to help the dynamic loader find the

    libraries (usually the bin subdirectory of the build tree).

    On Windows, the dynamic loader will look for shared libraries in

    the directory containing the executable, in directories listed in

    the PATH environment variable, and in some system directories.

    Since VTK places all of its executables and libraries in the same

    directory nothing needs to be set to get them to run.  However,

    when one builds outside projects against VTK the PATH environment

    variable must be set to point at the directory containing the VTK

    shared libraries.

    On UNIX-style platforms, the dynamic loader will use an

    environment variable such as LD_LIBRARY_PATH (Linux and many UNIX

    systems) or DYLD_LIBRARY_PATH (Mac OS X) to look for shared

    libraries.  In order to run VTK executables from the build tree

    one must set the appropriate environment variable to point at the

    directory containing the VTK shared libraries.  The same environment

    setting must be used for running outside projects build against the

    shared VTK libraries.

VTK_WRAP_TCL

    Enable/Disable automatic generation of VTK bindings in the Tcl

    language.  In order to build the Tcl-based VTK interpreter one

    will need to have Tcl and Tk version 8.2 or newer. Look to

      http://www.tcl.tk

    for information about getting Tcl and Tk. To turn on Tcl wrapping,

    set VTK_WRAP_TCL to ON during the configuration process.  One may

    then have to set the values for Tcl/Tk include directories and

    libraries during the next CMake configure iteration.  If there is

    more than one version of Tcl installed on the computer, make sure

    all the TCL_* and TK_* configuration options are set consistently

    to use the proper version.  This is especially important when

    Cygwin is installed because the Cygwin Tcl will not work for a

    native Windows VTK build and a Windows Tcl will not work for a

    Cygwin VTK build.  When building the Tcl/Tk wrappers on Cygwin one

    must also install the Cygwin sources for Tcl/Tk and set

    TK_XLIB_PATH to "/usr/src/tcltk-20030901-1/tk/xlib" or the

    corresponding directory for one's Cygwin Tcl version.  See

      Wrapping/Tcl/README

    for details on using the Tcl wrappers once they are built.

VTK_WRAP_PYTHON

    Enable/Disable automatic generation of VTK bindings in the Python

    language.  In order to build the Python-based VTK interpreter one

    will need to have Python installed. Look to

      http://www.python.org

    for information about getting Python.  To turn on Python wrapping,

    set VTK_WRAP_PYTHON and BUILD_SHARED_LIBS to ON during the

    configuration process.  One may then have to set the values for

    Python include directories and libraries during the next CMake

    configure iteration.  If there is more than one version of Python

    installed on the computer, make sure all the PYTHON_*

    configuration options are set consistently to use the proper

    version.  This is especially important when Cygwin is installed

    because the Cygwin Python will not work for a native Windows VTK

    build and a Windows Python will not work for a Cygwin VTK build.

    In order to use Tkinter with VTK-Python make sure that the Tcl/Tk

    libraries that are set correspond to the same version used by

    Tkinter.

    Note that the VTK-Python modules are now installed by default via

    'make install', which is a change from previous VTK versions.  The

    automatic python module installation is highly configurable. The

    Wrapping/Python/README.txt

    file documents the installation procedure and the VTK-Python

    modules.

CMAKE_INSTALL_PREFIX

    When VTK is installed all files are

    placed in a directory structure rooted at the directory specified

    by CMAKE_INSTALL_PREFIX.

Installation

Installing VTK from a source distribution requires first that it be

compiled in a build tree.  See the compilation section above for details.  Once

VTK has been compiled in a build tree one may build the install

target to actually put VTK in an installation tree.  If VTK was built

using a CMake Makefile generator then this is done by running "make

install" from the top of the build tree.  If VTK was built using a

CMake project file generator (such as Visual Studio), then building

the INSTALL project from inside the IDE will install VTK.  The

installation process will install all files in a directory structure

rooted at the directory specified by CMAKE_INSTALL_PREFIX.

Common Problems

  Strange compile errors on UNIX, typically involving system

      headers and types. Make sure that you specify the environment

      variables CC and CXX prior to running CMake.  If you have

      already run CMake you must create a fresh build-tree and start

      again.  If you ran CMake in the source tree then you must delete

      the source tree, re-extract the sources, and start again.

Errors on Tcl or Tk include files or libraries. Make sure that

      you set the TCL_* and TK_* configuration variables to the

      correct location when running CMake.

Link errors on Windows platforms. Make sure that the swap space is

      at least 300 MByte.

Link error with borland: TCL82.LIB contains invalid OMF record,

      type 0x21 (possibly COFF). You have to convert Tcl libraries

      from coff to omf with the Borland utilitiy coff2omf. Once you

      have created OMF versions, re-run cmake to tell it where the Borland

      versions of Tcl and Tk are located. Also, make sure that you are using

      Tcl/Tk 8.3.2.

Getting Data and Test Images

Many of the examples require data. There are two ways to get data. The

first is to download the file VTKData.tgz. The second is to access the

data via CVS checkout. The CVS checkout also includes many test images

used by the testing process (see http://public.kitware.com/dashboard.php).

These can be used if you wish to test VTK or submit testing dashboards.

The VTKData.tgz contains only data in compressed form is therefore can

be obtained much faster.

  1) Download the data at ftp://public.kitware.com/pub/vtk/VTKData.tgz

  2) Checkout the data from CVS using the following commands:

     cvs -d :pserver:[email protected]:/cvsroot/VTK login

        (there is no password...just press enter)

     cvs -d :pserver:[email protected]:/cvsroot/VTK checkout VTKData

Running VTK

Many C++ examples will be compiled if BUILD_TESTING and/or

BUILD_EXAMPLES are enabled in CMake. To run these C++ examples just

type their name. (They will be found in the binary build directory.)

If you have built shared libraries, make sure the PATH environment

variable (Windows) or the LD_LIBRARY_PATH (Unix) point to the shared

libraries (see above documentation of the BUILD_SHARED_LIBS for

details).

If you have enabled Tcl wrapping, you will want to set TCLLIBPATH to point to

the VTK/Wrapping/Tcl directory and check the instructions located in the Wrapping/Tcl/README file. You will then run

the VTK executable found in the bin directory where the code was

compiled. Assuming that the executable VTK is in your path, or has been

aliased, you would type:

  vtk mace.tcl

Note that most Tcl scripts allow you to type "u" in the render window to

obtain an interpreter. You can use the interpreter to modify the application

at run-time.

If you have enabled Python Wrapping you should read the instructions

located in the Wrapping/Python/README.txt file.

Writing Your Own Class There are several ways to

extend VTK. The simplest way is, in your own code, create classes that

inherit from the appropriate VTK classes.  Please see the

vtkLocal example

for instructions to build your classes outside VTK.

Getting Help / Mailing List

For general information go to the VTK web site

http://www.vtk.org

If you run into problems, your best bet is to join the VTK mailing list.

Visit 

http://www.vtk.org/mailman/listinfo/vtkusers to join the list.

Commercial support contracts are available from Kitware at

http://www.kitware.com/products/vtksupport.html.

Kitware also provides consulting services. Read more at

http://www.kitware.com/products/consult.html.

Training is also available from Kitware. See

http://www.kitware.com/products/vtktrain.html.

Ecosyste.ms: Awesome

https://github.com/starlink/vtk

Awesome Lists containing this project

README

Welcome To The Visualization Toolkit

Introduction

Copyright Notice

Organization

Documentation

Compilation

Building with CMake

Configuration Options in CMake

Installation

Common Problems

Getting Data and Test Images

Running VTK

Writing Your Own Class

Getting Help / Mailing List