
PyGTS - A python package for the manipulation of triangulated surfaces

  Copyright (C) 2009 Thomas J. Duck
  All rights reserved.

  Thomas J. Duck <tom.duck@dal.ca>
  Department of Physics and Atmospheric Science,
  Dalhousie University, Halifax, Nova Scotia, Canada, B3H 3J5


CONTENTS

  1. LICENSE
  2. SOFTWARE DESCRIPTION
  3. IMPORTANT FILES
  4. BUILD ENVIRONMENT
  5. INSTALLATION INSTRUCTIONS
  6. DOCUMENTATION


1. LICENSE

  Usage of this library is subject to the GNU Library General Public 
  Licence (LGPL) version 2 or higher.  See the file "LICENSE" for 
  information on the terms & conditions for usage of this software, 
  and a DISCLAIMER OF ALL WARRANTIES.


2. SOFTWARE DESCRIPTION

  PyGTS is a python package used to construct, manipulate, and perform
  computations on triangulated surfaces.  It is a hand-crafted and 
  "pythonic" binding for the GNU Triangulated Surface (GTS) Library.

  PyGTS lives on-line at http://pygts.sourceforge.net/ .


3. IMPORTANT FILES

  README - This file
  README.developers - Information for PyGTS developers/authors
  LICENSE - The software's license terms
  setup.py - The module setup script
  PKG-INFO - Python package info (auto-generated)
  
  src/* - PyGTS source files

  test/test.py - Unit tests for PyGTS
  doc/gts.html - Documentation for python module gts

  examples/polyhedrons.py - plots standard shapes
  examples/set_operations.py - union, difference, intersection
  examples/isosurface.py - function isosurfaces
  examples/plotgts.py - plots a gts file
  examples/seashell.gts - a sample gts file to use with plotgts.py


4. BUILD ENVIRONMENT

  PyGTS should, in principle, work with any python distribution with
  version 2.2 or greater, and on any unix-like operating system
  (including linux and Mac OS X).  The possibility for use with
  Windows is unknown.

  PyGTS is known to work with the following python versions and platforms:
 
    python 2.3 - Mac OS X (10.4)
    python 2.5 - Debian Linux (Lenny), Mac OS X (10.4)

  To build PyGTS, you will need to be sure that Python.h is installed with
  your python distribution.  For linux this often requires installing the 
  python-dev or python2.5-dev (or other version, as appropriate) package.

  The setup.py script requires the following utility, which is used
  to locate C header files and libraries:

    pkg-config - http://pkg-config.freedesktop.org/wiki/  

  The following libraries must be installed:

    gts - http://gts.sourceforge.net/
    glib-2.0 - http://library.gnome.org/devel/glib/index.html

  PyGTS has been verified to work with GTS 0.7.6 and numpy 1.1.1.  

  The following libraries are optional:

    numpy - http://numpy.scipy.org/

  Some advanced features may be disabled if the optional libraries are
  not found.

  The following python package (and all of its dependencies) is required
  for the examples:

    mayavi2 - http://pypi.python.org/pypi/Mayavi/3.2.0

  There are reports that at least one earlier version of mayavi2,
  v2.2, does not have the capabilities that PyGTS needs.  Please note
  that this is still a very early release of PyGTS, and if better (or
  alternative) display options become known, they will be used instead 
  (or in parallel).


5. INSTALLATION INSTRUCTIONS

  Please help by reporting any difficulties you have installing PyGTS
  to the mailing lists found at

    http://sourceforge.net/mail/?group_id=262159

  To upgrade from version 0.2.0 or earlier, first remove any installed
  PyGTS modules (gts.py, _gts.so) from python's site-packages directory.

  Unpack the distribution by entering

    tar -zxvf pygts.XX.XX.XX.tar.gz

  on the command-line.  Replace the XX's with the appropriate version
  numbers.

  To build PyGTS, cd into the distribution's directory and execute the 
  following:

    python setup.py build

  Install the software (as root) by entering:

    python setup.py install

  To test your installation, cd into the test directory and execute:

    python test.py

  You may also want to run the example programs as a further test:

    cd examples
    python polyhedrons.py
    python set_operations.py
    python isosurface.py
    python plotgts.py seashell.gts


6. DOCUMENTATION

  The documentation/api is provided in the python module.  To access it,
  type:

    1) "pydoc gts" - under bash to obtain a 'man'-like help file
    2) "pydoc -w gts" - under bash to write the file gts.html
    3) "help(gts)" - at the python prompt, after importing gts

  A pre-compiled gts.html file is given in the doc/ directory.
