Read Me
# $Id: README,v 1.9 2008/02/04 17:11:12 rsz 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 <ncvtk_dist_dir>/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.
10. Release
------------------------------------------------------------------------
Here are the steps to release ncvtk on SourceForge.
0. Checkout the latest source code
cd /tmp
cvs -d:pserver:anonymous@ncvtk.cvs.sourceforge.net:/cvsroot/ncvtk login
cvs -z3 -d:pserver:anonymous@ncvtk.cvs.sourceforge.net:/cvsroot/ncvtk co -P ncvtk
1. edit line in setup.py script
version = '2.4'
and
cvs ci setup.py
2. python setup.py sdist --formats=gztar,zip
this will create
bash-3.2$ ls -ltr dist/
total 660
-rw-rw-rw- 1 Alexander None 296946 Jan 4 10:44 ncvtk-2.4.tar.gz
-rwxr-xr-x 1 Alexander None 385758 Jan 4 10:44 ncvtk-2.4.zip*
3. Upload the files
cd dist
ftp upload.sourceforge.net
(anonymous)
bin
hash
cd /incoming
put ncvtk-2.4.tar.gz
put ncvtk-2.4.zip
3. on sf.net, go to Ncvtk -> Admin -> File Releases (Log in required)
Next to the ncvtk package name, click on "Add Release"
enter 2.4 (or whatever version)
select files in checkbox list and press "Add files"
select "platform independent" and file type
Done!