The hardest part of installing OOF3D can be installing the third party libraries that it uses. This page lists the required libraries and contains explicit instructions for installing them on several different operating systems.

The easiest way to install the libraries that OOF3D requires is to use a package manager, which will automatically configure, build, and install the libraries and all of the additional software that the libraries require. The tricky bit can be knowing which packages to request. This file gives explicit instructions for using package managers on OS X and various flavors of Linux.

NOTE: These instructions assume that you are a non-admin user, but have sudo privileges. If you are doing this from an admin or root account you may be able to omit the sudo from many of the commands listed here.

If you encounter difficulties with these instructions, please let us know.

[General] [Linux] [Macintosh OS X] [Building VTK]

Before installing OOF3D, the following software packages must be installed on your system. Detailed instructions for installing these packages on some computers are listed below.

(The OOF3D prerequisites are basically the same as the OOF2 prerequisites, except that OOF3D requires VTK instead of ImageMagick and OOFCanvas. OOF3D still uses an old version of SWIG, which is included in it, so it does not require SWIG to be installed.)

If you are using the binary installer for macOS, you do not need to install any of these prerequisites.

• A C++ compiler. This is standard on most Linux systems. On macOS, you need to install XCode.

• The Python scripting language, version 2.7. OOF3D does not work with Python 3. It might work with Python 2.6, but it hasn't been tested recently.

• The gtk+2 graphics toolkit. OOF3D requires version 2.6 or later, but not version 3.

• The pygtk Python bindings for the gtk+ library. OOF3D requires version 2.6 or later, but not as late as version 3.

• The BLAS basic linear algebra subroutines and the LAPACK linear algebra library. These are provided with many computer systems. Check to see if you have a native version before downloading and installing the generic code from netlib. On macOS, the BLAS and LAPACK routines are built in to the Accelerate framework and do not have to be installed separately.

• On, Linux, you need an X11 server. This is standard on most Linux systems. On macOS, X11 is optional. See macOS, below.

• The VTK Visualization Toolkit, version 8.1 or higher, including 9.0 and 9.1. OOF3D does not work with VTK 5 or 6. It might work, but poorly, with vtk 7. Some package management systems don't provide a sufficiently recent version of VTK, so you may need to download and install it manually. There are (possibly) helpful notes later on this page.

• Bison or yacc, for building oof's version of swig. These may already be installed on your system. Swig is included in the OOF3D distribution.

If your variety of Linux isn't listed and you successfully installed OOF3D on it, we would appreciate it if you'd tell us what you did, so that we can include your instructions here. Also, Linux distributions and packages sometimes change, so these instructions may be outdated. If they are, please let us know!

OpenSUSE

Run this command:

   sudo zypper install python-devel gtk2-devel python-gtk-devel liblapack3 lapack blas libblas3 vtk8 libbz2-devel libtool 

Ubuntu/Debian

Because OOF3D still requires gtk+2, it unfortunately can't be run on the most recent versions of Ubuntu. The latest that we've built it for is 18.04LTS (bionic). That distribution doesn't provide the required version of VTK, so you will have to build VTK manually. VTK 9.1 requires a later version of cmake than is available on Ubuntu 18.04, so use VTK 8.2 or 9.0. You can obtain 9.0 from github.

Run this command:

   sudo apt install python-gtk2-dev liblapack-dev bison 

See the instructions below for installing VTK.

RHEL and derivatives (CentOS/Scientific Linux/Oracle Linux)

Run this command:

   yum install gtk2-devel pygtk2-devel python-devel lapack-devel blas-devel bzip2-devel libtool gcc-c++ 

Some commonly used package managers on macOS are MacPorts, Homebrew, and fink. They all should work, but we have tested OOF3D only with MacPorts and have no experience with the others.

When the instructions below tell you to type a command, type it in a Terminal window. You can copy and paste the lines from this page.

OOF3D can be built to use either X11 graphics or native macOS graphics, referred to as "Cocoa" or "Quartz", depending on the context. NOTE: At the time of OOF3D 3.2.4's release, however, it doesn't seem to be possible to build VTK with X11, so follow the instructions below for Quartz/Cocoa.

Apple no longer supplies X11 with the OS, but you can install it from MacPorts (the package name is xorg-server). It can also be downloaded from XQuartz.

Whichever package manager you use, you will have to install Apple's Xcode tools, which are available through the App Store. MacPorts has a good discussion of the various ways of getting Xcode on different versions of macOS. After installing XCode, install its command line tools and agree to its license by typing these commands:

sudo xcode-select --install
sudo xcodebuild -license 

macOS with MacPorts and Quartz/Cocoa

The tricky part of installing OOF3D with MacPorts without X11 is that other packages that MacPorts has installed have to be installed without X11 too. If you already have other MacPorts packages installed, this is at best a pain and at worst impossible. Installation can take a long time, because using non-standard options means that MacPorts won't download any of its pre-compiled binaries.

Here are the steps:

1. Install MacPorts from http://www.macports.org/install.php, following their instructions. It's easiest to use the .pkg installer. If you get error messages when running "sudo port -v selfupdate", open a new Terminal window and try again.

2. Edit /opt/local/etc/macports/variants.conf and add the line

      -x11 +quartz 

   at the end.

3. Type these commands:

         sudo port install pkgconfig
         sudo port install py27-pygtk
         sudo port install vtk

   Optionally, run

         sudo port select python python27 
   

   which will make the default version of python 2.7. If you choose not to do this, when you build OOF2 just substitute python2.7 for python in the commands.

macOS with MacPorts and X11

This no longer seems to be possible, because VTK does not work in this configuration. If it did work, you should be able to follow the Quartz/Cocoa instructions above, skipping the variants.conf step, skipping sudo port install vtk, and addding sudo port install xorg-server. You will have to build VTK manually (see below), but that is where the problem lies.

These are instructions for building the visualization toolkit, VTK. They should be sufficient for OOF3D's purposes. They may not be sufficient for all purposes.

OOF3D requires VTK version 8.1 or 8.2, 9.0, or 9.1. It might build with VTK 6 or 7, but it's not likely to work correctly. It won't build with VTK 5.

These instructions assume you're using vtk 8.1.1. Where they refer to "8.1.1", substitute the actual version number of the version that you downloaded.

1. Download VTK 8.1.1 (or later) from the VTK download site. This will create a file called VTK-8.1.1.tar.gz in your download directory, which we'll assume is called ~/Downloads.

2. Create a directory to work in, and cd to it:

      mkdir ~/VTK
      cd ~/VTK 

3. Unpack the file:

      tar -xf ~/Downloads/vtk-8.1.1.tar.gz 

   which will create a directory called VTK-8.1.1. Read the README file within it.

4. Install vtk prerequisites.

   • On Debian/Ubuntu:

        sudo apt install cmake-curses-gui libtiff-dev mesa-common-dev libgl1-mesa-dev libxt-dev 

   • On macOS, with X11:

        sudo port install libGLU

   • On macOS, with Quartz/Cocoa, if you've installed the other OOF3D prerequisites, there should be no additional requirements for VTK.

5. There's a bug in vtk 8.1.1 that can be avoided by uncommenting two lines. Edit VTK-8.1.1/Rendering/OpenGL2/vtkSSAAPass.cxx and uncomment (remove the "//" from) lines 158 and 159. That is, change

      // this->FrameBufferObject->AddDepthAttachment(
      //   this->FrameBufferObject->GetBothMode()); 

   to

      this->FrameBufferObject->AddDepthAttachment(
      this->FrameBufferObject->GetBothMode()); 

   This is not necessary with VTK 8.2.0 or later.

6. cd to the directory containing VTK-8.1.1:

      cd ~/VTK 

7. Create a new directory called build-8.1.1, and cd to it.

      mkdir build-8.1.1
      cd build-8.1.1 

8. Run

      ccmake ../VTK-8.1.1 

   Type "c" to configure and "t" to get into advanced mode. Now you can set VTK configuration values. Make sure that these variables have these values:

   • BUILD_SHARED_LIBS = ON.

   • VTK_USE_SYSTEM_TIFF = ON (Not necessary with VTK 8.2.0 or later.)

   • VTK_USE_X = ON and VTK_USE_COCOA = OFF if you're using Linux or X11 on macOS, or VTK_USE_X = OFF and VTK_USE_COCOA = ON if you aren't using X11.

     NOTE for Mac Users: We have been unable to get VTK to work properly with X11 on Mac using recent versions of VTK and macOS. If you can get it to work, please tell us how. Otherwise, we recommend you build VTK and OOF3D to use Cocoa.

   • On macOS, if you're using Quartz/Cocoa, the three variables OPENGL_INCLUDE_DIR, OPENGL_gl_LIBRARY, and OPENGL_glu_LIBRARY should all be set to /System/Library/Frameworks/OpenGL.framework.

     If you're using X11 and MacPorts:

        OPENGL_INCLUDE_DIR = /opt/local/include
        OPENGL_gl_LIBRARY = /opt/local/lib/libGL.dylib
        OPENGL_glu_LIBRARY = /opt/local/lib/libGLU.dylib

   Type "c" to configure again. It's sometimes necessary to do it a few times before cmake will let you generate its makefile by typing "g".

9. Build vtk and install vtk:

      make
      sudo make install 

   This can take a while.