# $Id: README,v 1.8 2006/02/03 16:04:42 pletzer Exp $ 1. What is NCVTK? ------------------------------------------------------------------------ A program for exploring longitude/latitude based data stored in NetCDF file format. Ncvtk is built on top of the VTK toolbox. Ncvtk has been designed with the aim of offering a high degree of interactivity to scientists who have a need to explore three-dimensional, time-dependent planetary data. A more detailed overview may be found at http://ncvtk.sourceforge.net/. 2. Prerequisites ------------------------------------------------------------------------ - VTK. Recent versions of Ncvtk were tested with VTK 5.1. When installing VTK 5.x make sure to select: BUILD_SHARED_LIBS ON VTK_WRAP_PYTHON ON VTK_USE_RPATH OFF. - Python 2.4 or later (http://python.org/) - NetCDF: a portable, self-described binary file format (http://www.unidata.ucar.edu/software/netcdf/). Precompiled netCDF libraries for Win32 can be fetched at http://starship.python.net/~hinsen/ScientificPython/netcdf.dll. - Numerical Python: vector/matrix operations in python (http://sourceforge.net/projects/numpy). - ScientificPython (to read NetCDF files: http://starship.python.net/~hinsen/ScientificPython/). - Pmw: graphical user interface extension (http://pmw.sourceforge.net/). 3. Installing NCVTK ------------------------------------------------------------------------ - gunzip ncvtk-XXX.tgz where XXX is the version number - tar -xf ncvtk-XXX.tar - cd ncvtk-XXX - python setup.py install or python setup.py install --prefix=your_home_directory. By default, ncvtk will be installed relative to python's installation directory. The --prefix option allows you to install ncvtk in another directory, e.g. your_home_directory/bin, in which case the python modules will end up under your_home_directory/lib/pythonXXX/site-packages. If you use --prefix, make sure to have PYTHONPATH pointing to /pythonXXX/site-packages. 4. Running NCVTK ------------------------------------------------------------------------ "ncvtk2 -h" for a list of options. Typically you will need to type "ncvtk2 -f my_netcdf_file.nc" 5. Testing NCVTK ------------------------------------------------------------------------ - Download or create test_data.nc. This small file contains fields on a warped mesh. You can create it with the commands: cd /data python test_data.py - Type [python] ncvtk2. - Choose File -> Open to select a NetCDF file or test_data.nc. - Select, for instance, Visualize -> Color from the top tool bar. 6. Platform Specific Installation ------------------------------------------------------------------------ This shows steps taken by NCVTK users to install and configure the Prerequisites listed above. 6.1. Windows 2000 6.1.1 Download and Install Python 2.3.4 See http://www.python.org/2.3.4/ 6.1.2 Download and Install Numeric 23.1 for Python See http://prdownloads.sourceforge.net/numpy/Numeric-23.1.win32-py2.3.exe?download 6.1.3 Download and Install ScientificPython See http://starship.python.net/~hinsen/ScientificPython/ScientificPython-2.4.6.win32-py2.3.exe 6.1.4 Download and Install CMake See http://www.cmake.org/HTML/Download.html. 6.1.5 Download and Install VTK 4.5+ If there is a binary release of 4.5+, install it and goto 6.1.6. Notes: 1) Most binary releases of VTK don't have the pyhon extensions 2) Although Ncvtk should work with VTK 4.5, the latest code was tested with VTK 5.1. If there is no binary release, but there is a zip file for 4.5+, unzip it and goto 6.1.5.2. 6.1.5.1 CVS Checkout You may need a cvs client to get the latest source code for VTK. Try WinCVS at http://www.wincvs.org/download.html. CVS Checkout with WinCVS 1. Select Admin | Command Line... 2. Paste into the command text area: cvs -d :pserver:anonymous@public.kitware.com:/cvsroot/VTK login Click OK. 3. Navigate to where you want to save the files. Click OK. 4. You'll be queried for the VTK cvs password. Enter the password posted on the VTK website. 5. Select Admin | Command Line... again, erase the previous command, enter the command below, and then click OK: cvs -d :pserver:anonymous@public.kitware.com:/cvsroot/VTK checkout VTK 6.1.5.2 Compile VTK (with MS Visual Studio 6) 1. Start CMake and "Browse..." the source & build directories to where VTK resides. 2. Select your "Build For" environment. Here we'll MS Visual Studio 6. 3. Check "Show Advanced Values" 4. Click Configure. 5. Set BUILD_SHARED_LIBS to ON, CMAKE_INTALL_PREFIX to where VTK resides, ensure PTYHON_EXECUTABLE points to your recent Python installation, set VTK_USE_HYBRID to ON, set VTK_WRAP_PYTHON to ON. 6. Click Configure again. Errors related to Python may appear. If so, then set the path and file locations as indicated by CMake (red left column, NOTFOUND strings in the right column). It suffices to set PYTHON_LIBRARY ("python23.lib"), PYTHON_INCLUDE_PATH ("Python23\include"), and PYTHON_EXECUTABLE ("Python23\python.exe"). Click Configure again. If errors re-appear, continue to fix them. 7. Click OK to generate the make files. 8. Double-click VTK.dsw in the VTK source directory. 9. In the Visual Studio IDE, select Tools | Options | Directories. Add the Python include path, such as F:\home\rsz\apps\Python23\include. 10. Select "Library Files" from the "Show directories for" list. Add the Python libs path, such as F:\home\rsz\apps\Python23\libs. Click OK to close the window. 11. From the menu, select Build | Set Active Configuration, then "ALL_BUILD - Win32 Release". Click OK. 12. Compile with selecting from the menu Build | Build. 6.1.6 Set the PYTHONPATH Environment Variable You will need to point Python to directories of VTK and vtkLEA. In Windows, select Start | Settings | Control Panel | System | Advanced Settings | Environment Variables. If PYTHONPATH doesn't exist in the system variables, add it with "New...". Set the text so it includes the python directories of VTK and vtkLEA, such as F:\home\rsz\apps\VTK\bin\Release;F:\home\rsz\apps\VTK\Wrapping\Python;F:\home\rsz\projects\vtkLEA\bin\Release 6.2 Mac OS X These instructions were provided by Takeshi Enomoto (01/22/2006). The installation was based on Tcl/Tk 8.4.12, python 2.4.2, Pmw-1.2, Numeric-24.2, numarray-1.5.0, ScientificPython-2.4.9 and VTK-5.1 from CVS. Tk, python, and VTK were configured to use Carbon. * Make Tcl and Tk in macosx directory. * Configure python with --enable-framework option. * Compile VTK with VTK_USE_CARBON=ON. * I had to make a sym link of /usr/local/lib/python2.4/site-packages/ vtk in /Library/Frameworks/Python.framework/Versions/2.4/lib/ python2.4/site-packages/. * ncvtk, ncvtk2 are installed in /Library/Frameworks/ Python.framework/Versions/2.4/bin. I moved them to /usr/local/bin. 7. Documentation ------------------------------------------------------------------------ Novice users may want to consult the tutorial at http://ncvtk.sf.net/ncvtk_tutorial.pdf. Keep in mind that Ncvtk is work in progess and that many graphical user elements are still evolving. A list of module documentation can be obtained at http://ncvtk.sf.net/doc.htm 8. Known problems ------------------------------------------------------------------------ A ist of known problems can be found at http://sourceforge.net/tracker/?group_id=113178&atid=664312 9. Loose ends ------------- This information is mainly useful to developers at this stage. 9.1 How to build a C++ extension under Windows: 1. Run CMakeSetup, and set the source & build directories to where the ncvtk vtkLEA directory is, such as F:\home\rsz\projects\ncvtk\ncvtk\vtkLEA. 2. Check "Show Advanced Values" and click Configure. 3. Add to CMAKE_CXX_FLAGS and CMAKE_C_FLAGS the Python include directory, e.g. /I f:\home\rsz\apps\Python23\include. 4. Click OK to exit. 5. Double-click "vtkLEA.dsw" that CMake generated in the ncvtk source directory. This will open up the Visual Studio IDE. 6. Set the Active Configuration to Release, and then Build. 7. The new libraries will be in the directory labeled LIBRARY_OUTPUT_PATH in CMake, e.g. F:\home\rsz\projects\ncvtk\ncvtk\vtkLEA\bin\Release.