.. $Id$    -*- rst -*-
  
..
  This file is part of pyFormex 0.9.1  (Tue Oct 15 21:05:25 CEST 2013)
  pyFormex is a tool for generating, manipulating and transforming 3D
  geometrical models by sequences of mathematical operations.
  Home page: http://pyformex.org
  Project page:  http://savannah.nongnu.org/projects/pyformex/
  Copyright 2004-2013 (C) Benedict Verhegghe (benedict.verhegghe@ugent.be)
  Distributed under the GNU General Public License version 3 or later.
  
  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.
  
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with this program.  If not, see http://www.gnu.org/licenses/.
  
  
What is pyFormex?
=================
pyFormex is a tool for generating, manipulating and transforming large
geometrical models of 3D structures by sequences of mathematical 
transformations. Thanks to a powerful (Python based) scripting language,
pyFormex is very well suited for the automated design of spatial frame
structures. It provides a wide range of operations on surface meshes, 
like STL type triangulated surfaces. There are provisions to import medical 
scan images. pyFormex can also be used as a pre- and post-processor for 
Finite Element analysis programs. Finally, it might be used just for 
creating some nice graphics.

Using pyFormex, the topology of the elements and the final geometrical form
can be decoupled. Often, topology is created first and then mapped onto the
geometry. Through the scripting language, the user can define any sequence
of transformations, built from provided or user defined functions. 
This way, building parametric models becomes a natural thing.

While pyFormex is still under development (see the project page at
http://savannah.nongnu.org/projects/pyformex/), it already provides a
fairly stable scripting language and an OpenGL GUI environment for
displaying and manipulating the generated structures. 


Installation
============

We detail here only the installation on Linux platforms.


Prerequisites
------------- 
Essential:

- python: http://www.python.org  (version 2.4 or higher; 2.5 recommended)
- numpy: /http://numpy.scipy.org/ (version 1.0 or higher; 1.1 recommended)
- Qt4: http://www.trolltech.com/products/qt
- PyQt4: http://www.riverbankcomputing.co.uk/pyqt/index.php
- PyOpenGL: http://pyopengl.sourceforge.net/

To compile the acceleration library (highly recommended!), you will also
need the appropriate header Python and OpenGL header files.

Further, we recommend to install the following for extended functionality:

- python-gnuplot
- python-doc
- python-scipy
- units
- imagemagick
- admesh

For the following extensions, which are not easily packaged format,
an install script is provided in this distribution.

- calpy
- pygl2ps
- gts
- tetgen


Easy way to install prerequisites on Debian GNU/Linux or Ubuntu
---------------------------------------------------------------
On Debian (lenny) systems (and Debian-derivatives like Ubuntu) you can install
all basic prerequisites and their dependencies with the command::

  apt-get install python-qt4-gl python-numpy

If you want to compile the acceleration library (which is highly recommended) you also need the header files::

  apt-get install python-dev libgl1-mesa-dev

Install the extras::

  apt-get install python-gnuplot python-doc python-scipy units imagemagick admesh

Howto install pyFormex:
-----------------------
If a previous version of pyFormex was already installed on your system,
you may want to remove the older version first before installing the new one.
See further (Howto uninstall pyFormex)

We suppose you have installed all the prerequisites and downloaded the
pyformex source tarball: pyformex-VERSION.tar.gz

Unpack the pyFormex source tarball::

  tar xvzf pyformex-VERSION.tar.gz

Go to the created pyformex directory::

  cd pyformex-VERSION

Do (with root privileges) ::
  
  python setup.py install --prefix=/usr/local

This will install pyFormex under /usr/local/. You can change the prefix
to install in some other place.

After installation you can remove the directory where you unpacked the tarball.

The installation procedure installs everything into a single directory,
and creates a symlink to the executable in /usr/local/bin.
You can use the command pyformex --whereami to find out where pyFormex
is installed.

If you have xdg-utils on your system, the installation procedure will also
install a menu and desktop starter for pyFormex.


Howto uninstall pyFormex:
-------------------------
A pyFormex installation of version 0.5 or later can be removed with the command ::

  pyformex --remove

and then answering 'yes' to the question.


 
Howto install the extra packages
-----------------------------------
pyFormex makes use of extra software components to enhance its functionality.
While they are not required for the core operation of pyFormex, many users may
want to install them. Some of these extras (admesh, units) can easily be
installed from your regular distribution repositories.
Some extra components however either are not available in packaged format, or
the existing packages do not work together well with pyFormex.
For these components, the pyFormex distribution contains an adhoc install
procedure to help our users with the installation. The procedures are located
in dedicated subdirectories of the pyformex-VERSION/pyformex/extra directory
of the unpacked release tree. Each subdirectory contains a ``README`` file
with installation instructions. It the directory contains a ``Makefile``, this
usually boils down to the usual::

  make
  make install

Else, an install script ``install.sh`` is included and installation can be done
with by executing it from within the subdirectory, with root privileges and with a single parameter 'all'::
 
  (sudo) ./install.sh all

- gts: Installs some programs to do operations on triangulated surfaces. You need to have the ``libgts`` and its header files installed. On Debian::

    apt-get install libgts-dev

- dxfparser: Installs the command ``pyformex-dxfparser``, to preprocesses AutoCAD .DXF
  files for import into pyFormex. 
- postabq: Installs the command ``pyformex-postabq``, to preprocess Abaqus output files (.fil) for import into pyFormex. 
- gl2ps: Image output to in vector formats (PS, EPS, PDF and SVG). Requires
  a Python interface, provided by our install procedure. 
- calpy: Simple finite element simulation framework. Needed for the ``*_calpy`` 
  examples. Has to be installed from source, because is has to be compiled
  against the same numpy version as pyFormex itself.


Running pyFormex from Subversion (SVN) sources
----------------------------------------------
If the officially released pyFormex packages are not suitable for your needs,
you can try installing pyFormex from the Subversion sources. Besides the basic 
prerequisites (see above), you will also need to have 'Subversion' installed.

The `SVN repository`_ on the developer site is accessible by anonymous SVN.
The command ::

  svn co svn://svn.savannah.nongnu.org/pyformex/trunk/pyformex MYDIR

will checkout the source to a local directory ``MYDIR``. Provided you have all the prerequisites installed, pyFormex can then be run directly from the checked out source with the command::

  MYDIR/pyformex/pyformex
 
If you want to use the compiled accelerator library however, you will have to
create it first::

  cd MYDIR
  make lib

Once you have a checked-out source tree, you can easily sync it to the latest
repository version by just issuing the following command from your checkout
directory::

  svn up

Documentation
=============

The documentation is included with the pyFormex distribution. Execute the command
pyformex --whereami to find out where the pyformex files are
installed. The pyformex path contains a directory doc/html with the
full html ocumentation.
When working with the pyFormex GUI, you can load this local documentation in your browser
using the help menu, or view the online documentation at
http://pyformex.org/doc.

To use pyFormex, you create a script that builds a structure layout and 
geometry. Look at the examples to get the feeling of how it is working. 
Use the File->Play menu selection to display the structure. 

The examples and the Python source are relatively well documented.


Help and Feedback
=================

For any questions or feedback, please go to the pyFormex support tracker at
http://savannah.nongnu.org/support/?group=pyformex

If you find any bugs or malfunctions in pyFormex, please submit them to
the pyFormex Bug tracker http://savannah.nongnu.org/bugs/?group=pyformex

.. _`SVN repository`: http://savannah.nongnu.org/svn/?group=pyformex

.. target-notes::

.. End
