Installing pyFormex

Abstract

This document explains the different ways for obtaining a running pyFormex installation. You will learn how to obtain pyFormex, how to install it, and how to get it running.

Warning

This document is under construction

Installing pyFormex-2.0

This installation manual is for the pyFormex 2.0 series. For older versions see Installing pyFormex-1.0 or Installing pyFormex-0.9.

pyFormex is being developed on GNU/Linux systems and currently only runs on Linux. On other systems your best option is to run Linux in a virtual machine or boot your machine from a USB stick with a Linux Live system.

pyFormex is software under continuous development, and many users run it directly from the latest development sources. This holds a certain risk however, because the development version may at times become unstable or incompatible with previous versions and thus break your applications. At regular times we therefore create official releases, which provide a more stable and better documented and supported version, together with an easy install procedure.

If you can meet the requirements for using an officially packed release, and you can not use the deb packages, this is the recommended way to install pyFormex. All the software packages needed to compile and run pyFormex can be obtained for free.

To install an official pyFormex release, you need a working GNU/Linux system, root privileges to the system (whether through su or sudo, and you need to make sure that the Dependencies listed below are installed first on the system. Then preceed to Install an official pyFormex release.

If you need to install a new GNU/Linux system from scratch, and have the choice to pick any distribution, we highly recommend Debian GNU/Linux or derivatives. This is because most of the pyFormex development is done on Debian systems, and below you’ll find precise instructions to install dependencies on Debian. Also, the Debian software repositories are amongst the most comprehensive to be found on the Internet. Furthermore, we often provide deb packages as well, making installation really a no-brainer.

Most popular GNU/Linux distributions provide appropriately packed recent versions of the dependencies, so that you can install them easily from the pacakge manager of your system. In case a package or version is not available for your system, you can always install it from source. We provide the websites where you can find the source packages.

Dependencies

Whether you install an official release package of pyFormex, or you run pyFormex from the development source tree, you need to have the following installed (and working) on your computer:

Python

Version 3.6 or higher, 3.7 is recommended. Nearly all GNU/Linux distributions come with Python installed. Some may however still have Python2.x installed as the default Python. Python2.x is however no longer supported by pyFormex, so you may have to install the Python3 version. Usually, the Python 3.x executable is named ‘python3’, and pyFormex expects it that way. To check your version, do:

python3 --version
NumPy

Version 1.10 or higher, 1.12 recommended. NumPy is the package used for efficient numerical array operations in Python and is essential for pyFormex.

PIL

The Python Imaging Library from the pillow fork, used for loading and saving images in lots of formats.

Qt5 or Qt4

Qt is the widget toolkit on which the pyFormex Graphical User Interface (GUI) is built. We recommended Qt5, but the older Qt4 version should also still work.

PySide2 or PyQt5

These are Python bindings for the Qt5 libraries. We recommend Pyside2, though it should not be too difficult to make PyQt5 work as well. If you opted for the older Qt4 libraries instead, you should use one of PySide (recommended) or PyQt4. In any case, make sure you have the bindings for Python3.

PyOpenGL

Python bindings for OpenGL, used for drawing and manipulating the 3D-structures.

admesh

Used to check and fix STL files. We need the binary, not the Python library.

libgts-0.7-5

A library for operating on triangulated surfaces.

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:

  • make

  • gcc

  • python3-dev

  • libglu1-mesa-dev

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

  • python3-gnuplot or python3-matplotlib

  • python3-pydicom

  • python3-docutils

  • python3-scipy

  • units

  • imagemagick

  • tetgen

  • libdxflib3

Finally, while pyFormex has interfaces to use some of the functionality of vtk and vmtk, we can not really advise you to install ‘python3-vtk7’ or ‘vmtk’, unless you really need these packages. The reason is that their list of dependencies is too long. On my Debian Buster ‘python3-vtk7’ pulls 76 other packages, and that is with the ‘–no-install-recommends’ option. And ‘vmtk’ pulls in another 92, many of them the same as the vtk ones, but Python2 versions.

Installing dependencies on Debian and alikes

On Debian GNU/Linux systems (and Debian-derivatives like Ubuntu) you can install all basic prerequisites and recommended packages and all their dependencies with the following command:

(sudo) apt install \
  python3 make gcc git \
  python3-numpy python3-scipy python3-pil python3-opengl \
  python3-pyside2.qtcore python3-pyside2.qtgui python3-pyside2.qtwidgets \
  python3-pyside2.qtopengl \
  python3-matplotlib python3-pydicom python3-docutils python3-sphinx \
  python3-dev libglu1-mesa-dev libfreetype6-dev \
  libgts-dev libgts-bin admesh tetgen units libdxflib-dev \
  python3-pytest

Install an official pyFormex release

Download pyFormex

Official pyFormex releases can be downloaded from Releases. As of the writing of this manual, the latest release is 3.1.

pyFormex is distributed in the form of a .tar.gz (tarball) archive. See Install pyFormex: the short version for how to proceed further with the downloaded file.

Install pyFormex: the short version

Once you have downloaded the tarball, unpack it with the command

tar xvzf pyformex-VERSION.tar.gz

where you replace VERSION with the correct version from the downloaded file. Then go to the created pyformex directory

cd pyformex-VERSION

and execute the following commands:

make build
sudo make install

This will build pyFormex and install it under /usr/local/. You need root privileges for the install step only. The executables are put in /usr/local/bin. If all goes well, you can safely remove the source tree and build temporaries

cd ..
rm -rf pyformex-VERSION

and you may start pyFormex with the command:

pyformex

If not, or if you want more details about the install procedure, or want to customize the installation procedure, read on in the next section.

Install pyFormex: the long version

The make commands in Install pyFormex: the short version do two things. As can be seen from the Makefile, make build actually executes:

python3 setup.py build
make -C pyformex/extra build

The first of these commands builds the Python code of pyFormex and compiles some acceleration libraries. The second command compiles some external programs that are located under pyformex/extra.

If something goes wrong with the make build, or if you need to do some customized build/install procedures, you can use these commands separately, or customize the Makefile.

As you expect, the make install command executes the same two commands as above, with install in place of build. The installation procedure installs everything into a single directory (default under a subdirectory of /usr/local/lib/Python3.x/), and creates an executable pyformex in /usr/local/bin. If you have xdg-utils on your system, the installation procedure will also install a menu and desktop starter for pyFormex.

If installation succeeded, you can use the command

pyformex --whereami

to find out where pyFormex is installed. If the binary install path /usr/local/bin is not up front in your PATH settings, you may have to use the full path name: /usr/local/bin/pyformex.

You can not run the pyformex command from inside the unpacked pyformex-VERSION directory. This will force a failure, because doing so would use the Python source files in that directory instead of the built and installed ones.

Next you can run

pyformex --detect

to give you a list of installed and detected software that pyFormex is able to use as helpers. Check that you have pyFormex_installtype (R) and pyFormex_libraries (pyformex.lib.misc_, pyformex.lib.nurbs_). The gts, gts-bin and gts-extra packages do not have a version, and just display ‘:’.

If you have troubles with building the externals, you can build each of the externals separately. In each of the subdirectories of pyformex/extra you can do make build and sudo make install. Actually only the pyformex/extra/gts/ is of high importance. Most users can do without the other ones.

Uninstall pyFormex

When pyFormex is installed by the procedure above, it can be removed by executing the command

pyformex --remove

and answering ‘yes’ to the question. You may want to do this before installing a new version.

deb packages

Currently we have no .deb packages ready for pyFormex 2.0. When they become available, this documentation will be updated.

Running pyFormex from sources

If the officially released pyFormex packages are not suitable for your needs, and you can not find proper packages for your distribution, you can try running pyFormex directly from the source in the git repository. Besides the Dependencies for the official release, 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