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.
This document is under construction
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.
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:
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:
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.
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.
Python bindings for OpenGL, used for drawing and manipulating the 3D-structures.
Used to check and fix STL files. We need the binary, not the Python library.
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:
Furthermore, we recommend to install the following for extended functionality:
python3-gnuplot or python3-matplotlib
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¶
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
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:
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
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
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
and creates an executable
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
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:
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
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.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
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
When pyFormex is installed by the procedure above, it can be removed by executing the command
and answering ‘yes’ to the question. You may want to do this before installing a new version.
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:
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: