..  -*- rst -*-
  
..
  This file is part of pyFormex 1.0.7  (Mon Jun 17 12:20:39 CEST 2019)
  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-2019 (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.7 recommended)
- numpy: /http://numpy.scipy.org/ (version 1.0 or higher; 1.1 recommended)
- PIL: https://python-pillow.org/ (python-pil)
- Qt4: http://www.trolltech.com/products/qt
- PyOpenGL: http://pyopengl.sourceforge.net/
- PySide: http://www.pyside.org/
- admesh
- libgts

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

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

- python-gnuplot
- python-doc
- python-scipy
- units
- imagemagick
- tetgen
- libdxflib3


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

- calpy
- pygl2ps
- gts apps


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

  apt-get install python-numpy python-opengl python-pyside python-pil

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

  apt-get install make gcc python-dev libgl1-mesa-dev libglu1-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

Then do (with sudo or as root)::

  (sudo) python setup.py install

to build pyFormex and some extra utilitites, and install everything
under /usr/local.

.. Note: The installation path for pyFormex can be changed in the file conf.py.

If you wish, you can first build everything, and only then do the
installation. Building does not require root privileges::

  python setup.py build
  (sudo) python setup.py install

After successful installation of pyFormex, you may also want to build
and install some extra binaries that are often used by pyFormex. To do so,
enter the commands (still from the pyFormex unpacking directory)::

   make -C pyformex/extra build
   (sudo) make -C pyformex/extra install

While pyFormex program is build in a subdirectory `build`, the extra
utilities are build in their own `pyformex/extra` subdirectories.


After installation you can remove the whole directory where you unpacked
the tarball and built pyFormex.

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.


Install and run the Python3 version of pyFormex
-----------------------------------------------
As of pyFormex 1.0.6, Python3 is supported and provides nearly full
functionality. See the file 'p3.rst' for details about the required
packages. Installing the Python3 version is done just like for the
Python2 installation, only use the 'python3' command in place of 'python'::

  python3 setup.py install

To run the Python3 version of pyFormex, add '-3' as first option to the
'pyformex' command::

  pyformex -3

You can also set an environment variable::

  PYFORMEX_PYTHON=3

This will make the Python3 version the default. You can then still execute
the Python2 version with, surprise::

  pyformex -2

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
  (sudo) 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


Prerequisites: on Debian::

  apt-get install gcc g++ pkg-config make
  apt-get install python-dev libglu1-mesa-dev
  apt-get install libgts-dev libdxflib-dev


- gts: Installs some programs to do operations on triangulated surfaces. You need to have the ``libgts`` and its header files installed.
- dxfparser: Installs the command ``pyformex-dxfparser``, to preprocesses AutoCAD .DXF files for import into pyFormex. You need to have the ``libdxflib`` and its header files installed.
- 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 sources
-----------------------------
If the officially released pyFormex packages are not suitable for your needs,
you can try installing pyFormex from the source in the git repository.
Besides the basic prerequisites (see above), you will also need to have
git installed.

The `GIT repository`_ on the developer site is accessible anonymously.
The command ::

  git clone https://git.savannah.nongnu.org/git/pyformex.git 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::

  git pull

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

.. _`GIT repository`: http://savannah.nongnu.org/git/?group=pyformex

.. target-notes::


Copyright
=========

pyFormex is distributed under the GNU GPL version 3 or later.

The main author claims that he wrote this software in his free time,
for his joy, not as a commissioned task. Any copyright claims made by
his employer (previous, current or future) should therefore be considered
void.

Over the years, other members of the pyFormex team have made valuable
contributions. These were made with full consent of the contributor that
they could be used at will inside the pyFormex project and were free of
other copyright claims.

.. End
