Table of Contents
On the website www.ovito.org you find a couple of binary packages for several target platforms. If you don't find a suitable package for your system or if you want to have the newest version of OVITO then you should compile the source code yourself. The following sections will give you the necessary instructions.
OVITO has been developed on Linux systems. But its code design is platform-independent, hence it should run on all platforms that are supported by the Qt framework. At least in principle. In addition to Linux, these include Microsoft Windows and MacOS.
Building the source code on a Windows computer with Visual C++ is possible, but you will have to fetch all required libraries from the Internet first. Up to now, OVITO has never been built on a MacOS computer. But if someone has such a computer, I would be very curious to see if it works.
Linux is the best choice for running OVITO. Depending on the Linux distribution installed on your computer the compilation of the source code can be more or less work. Recent versions of Linux already come with all necessary packages and third-party libraries required to build OVITO. They can be installed through the appropriate administrative tools of your Linux distribution. Note that, to be able to install all required packages, you might need superuser privileges or ask your administrator to do it for you.
In case you have an older version of Linux installed on your computer you'll probably have to download and manually build the missing libraries before you can start building the OVITO source code. I will give a detailed list of required packages below.
During its development OVITO has been tested on the following platforms and operating systems:
OVITO is a complex software package that makes use of several functions provided by third-party libraries. These libraries must be available on your computer to successfully build and run OVITO. Also note that OVITO is a modular software. During the build process you can choose which parts of the package should be built. Accordingly, only those third-party libraries need to be available on your system that are required by the modules of OVITO you intend to build. Here is the complete list of things you will need to build OVITO:
The following repository packages are required to build OVITO:
subversion cmake cmake-curses-gui g++ libboost-dev libboost-iostreams-dev libboost-python-dev povray libqt4-opengl-dev qt4-dev-tools libgsl0-dev xsltproc docbook-xml docbook-xsl docbook-xsl-doc-html libqscintilla2-dev python-dev
Use the command sudo apt-get install followed by the above list of packages to install.
The following repository packages are required to build OVITO:
subversion cmake cmake-curses-gui g++ libboost1.38-dev libboost-iostreams1.38-dev libboost-python1.38-dev povray libqt4-opengl-dev qt4-dev-tools libgsl0-dev xsltproc docbook-xml docbook-xsl docbook-xsl-doc-html libqscintilla2-dev python-dev
Use the command sudo apt-get install followed by the above list of packages to install.
Unfortunately, the Python support of the Boost library (v1.38) that comes with Ubuntu 9.10 is broken. Thus, if you want Python scripting support in OVITO then you'll have to download and build your own version of the Boost library first.
The following repository packages are required to build OVITO:
subversion cmake g++ libqt4-dev libqt4-opengl-dev qt4-dev-tools python-dev libboost-python-dev libboost-iostreams-dev libqscintilla-dev povray povray-includes libgsl0-dev xsltproc docbook-xml docbook-xsl docbook-xsl-doc-html
Use the command sudo apt-get install followed by the above list of packages to install them.
Ubuntu 8.04 comes with an outdated version of the Qt library. You need to activate "Unsupported updates" (hardy-backports) in the Synaptic package manager to get the required version 4.4 of the Qt library. The following repository packages are required to build OVITO:
subversion cmake g++ libqt4-dev libqt4-opengl-dev qt4-dev-tools python-dev libboost-python-dev libboost-iostreams-dev libqscintilla2-dev povray povray-includes libgsl0-dev xsltproc docbook-xml docbook-xsl docbook-xsl-doc-html
Use the command sudo apt-get install followed by the above list of packages to install them.
The following repository packages are required to build OVITO:
subversion cmake gcc-c++ libqt4-devel libqt4-devel-doc boost-devel python-devel libqscintilla-devel libxslt docbook-xsl-stylesheets povray gsl-devel
Unfortunately, the Boost library headers (v1.39) that come with OpenSUSE 11.2 conflict with the Python headers.
Thus, if you want Python scripting support in OVITO then you'll have to patch the Boost header file /usr/include/boost/foreach.hpp
first
(see this link).
The following repository packages are required to build OVITO:
subversion cmake gcc-c++ qt-devel boost-devel python-devel qscintilla-devel gsl-devel docbook-style-xsl libxslt redhat-lsb
Unfortunately, the Boost library headers (v1.39) that come with Fedora 12 conflict with the Python headers.
Thus, if you want Python scripting support in OVITO then you'll have to patch the Boost header file /usr/include/boost/foreach.hpp
first
(see this link).
The following repository packages are required to build OVITO:
subversion make g++ libqt4-dev libqt4-opengl-dev qt4-dev-tools python-dev libboost-dev libqscintilla2-dev libgsl0-dev xsltproc docbook-xml docbook-xsl docbook-xsl-doc-html
Use the command apt-get install followed by the above list of packages to install them.
Version 2.6.0 of cmake that is provided by Debian contains a bug related to relative library RPATHs. You should download a newer version from www.cmake.org and use it for building OVITO.
The newest source code for OVITO can be obtained from the SourceForge repository. To this end, you need a Subversion client program (usually called svn) to download the code into a local directory on your computer. The Subversion client svn is included in most Linux distributions. You should create an empty directory for the OVITO source code first. Use the following command line to download the source code from the repository for the first time:
svn checkout http://ovito.svn.sourceforge.net/svnroot/ovito/trunk/ .
Pay attention to the dot at the end of the line denoting the destination directory. This command downloads the complete source code including all auxiliary files into the current directory.
New features and bug fixes will be added to the source code in the Subversion repository from time to time. You can update your local copy of the source code at any time by running the command
svn update
in the same directory. This will download only those files from the server that have been changed since the last download.
The next section describes how the executable is built from the source code.
The CMake build tool is required to compile OVITO. CMake is a platform and compiler-independent makefile generator that comes with many Linux distributions. The OVITO source package includes a project file for CMake, which is used to generate a platform-dependent makefile that can then be compiled using the standard GNU make tool.
The first step is to create a second directory in addition to the source directory. This will be the so-called build directory and it should not be located inside the source directory into which you have downloaded the source code. From inside the newly created build directory run the following command:
ccmake [path_to_source]
Replace [path_to_source] with the relative or absolute path to the source directory into which you have downloaded the OVITO source files in the previous step. ccmake is the CMake configuration program that lets you configure the build settings for the OVITO project. This introduction provides some more hints on the usage of this tool.
The configuration of the build options in the ccmake program is an iterative process. You first press the c key to let CMake parse the project file. After this first configuration step ccmake will present you a list of build settings that you can change.
CMake tries to automatically locate all libraries on your computer that are required for building OVITO. If it is not able to find one of them (either because it's missing or maybe because it has not been installed in a default directory sp ccmake can't find them) CMake will print an error message and you will have to enter the path to the library manually in the ccmake configuration program. The OVITO project is configured such that only those libraries must be present, that are required for the program components you have activated.
The OVITO project file defines several options that can be changed in the ccmake configuration program to customize the build process and the program components (plug-ins) to be built:
Table 2.1. CMake project configuration options
CMake options | Description |
---|---|
CMAKE_BUILD_TYPE | This should be set to the value Release to build the OVITO executable with all speed optimizations turned on. |
CMAKE_INSTALL_PREFIX | Specifies the path into which the compiled program will be installed if you run make install. |
OVITO_BUILD_DOCUMENTATION | Controls the generation of the HTML documentation files. The OVITO manual is written in the Docbook XML format and needs to be translated to the HTML format before it can be viewed in a web browser. You will need special tools as discussed in the prerequisites section to do this. |
OVITO_BUILD_PLUGIN_ATOMVIZ | This boolean option controls whether the AtomViz plugin is built. This should be set to ON. |
OVITO_BUILD_PLUGIN_CRYSTALANALYSIS | This option controls whether the CrystalAnalysis plugin is built. It provides specific functions for the analysis of crystal structures. |
OVITO_BUILD_PLUGIN_POVRAY | This boolean option controls whether the POV-Ray plugin is built. Setting this option to ON makes only sense when the POV-Ray renderer is available on your computer. |
OVITO_BUILD_PLUGIN_RENDERMAN | This boolean option controls whether the RenderMan interface plugin is built. Setting this option to ON makes only sense when a RenderMan compatible renderer is available on your computer. This component is an experimental feature that you probably don't need. |
OVITO_BUILD_PLUGIN_SCRIPTING | This boolean option controls whether the scripting plugin is built. When this option is set to ON then OVITO and all other plugins will be built with scripting support enabled and the Python interpreter and Boost.Python must be present on your computer. |
OVITO_BUILD_PLUGIN_SCRIPTING_GUI | This boolean option controls whether the graphical user interface for the scripting plugin is built. This feature is not required to use scripting functions from the console or stand-alone Python scripts. It's in a very initial state, so you probably don't need this component. |
OVITO_BUILD_PLUGIN_STDOBJECTS | This boolean option controls whether the plugin that provides the standard object types is built. |
OVITO_MONOLITHIC_BUILD | Turn this on to build OVITO as a single static executable. By default OVITO is build as a collection of smaller plugin modules (shared libraries) that can be extended. In a monolithic build all plugins and all third-party libraries are linked into a single file that can more easily be transfered to another computer. Please note that this is still an experimental feature and has not fully been tested. |
OVITO_USE_DOUBLE_PRECISION_FP | This boolean option controls whether 64 bit (ON) or 32 bit (OFF) floating-point numbers should be used for all computations in OVITO. Singe precision numbers (32 bit) are usually sufficient for visualization purposes. They also save a lot of memory when you work with a large number of atoms. Double precision numbers (64 bit) may only be required in some cases for very exact analysis calculations. |
OVITO_USE_PRECOMPILED_HEADERS | This controls the generation of precompiled headers when using the GCC compiler. Precompiled headers speed up the compilation process and are turned ON by default. |
Please do not forget to set the CMAKE_BUILD_TYPE setting to either Release
or Debug
since it has no valid default value.
After all options have been specified in the CMake configuration program and CMake does not complain about any missing libraries you finally can press the g key to generate the makefile. This will also exit the ccmake program. Now run
make
This will start the build process. If you have a computer with a modern multi-core processor than you can speed up the build process by adding the parameter -j2 to the make command. Then, multiple source files will be compiled in parallel (two files simultaneously in the example; you can specify a higher number if your processor has more cores).
A more detailed description of the ccmake configuration program and the necessary steps to build a CMake project can be found in the CMake documentation or on this page.
foreach.hpp
of Boost.
After you have successfully compiled OVITO you can start the program as described in the next section. OVITO is constantly being enhanced, new features are made available in the SourceForge repository. To upgrade to a newer version of OVITO you just have to perform two simple steps: First run the command svn update in the OVITO source directory to fetch the newest source code changes from the server. After that, just run make in the build directory to recompile OVITO. Re-running the ccmake program is usually not necessary.
Optionally, you can install OVITO to an installation directory by running make install.
The installation directory is set with the CMAKE_INSTALL_PREFIX
configuration variable in CMake.
The default directory is /usr/local
which usually requires superuser priviliges to install, i.e.
you have to run
sudo make install
to install it in this location. For a personal installation in your home directory I would recommend not to install OVITO at all; just leave the compiled executable in the build directory and run it from there.
After successful compilation the build directory will contain an executable file named ovito (when using Unix/Linux) or ovito.exe (when using Windows). Execute this file to start the OVITO application. The following command line options can be passed to the ovito command:
Table 2.2. OVITO command line options
Command line option | Description |
---|---|
--script Scriptfile.py ... | Executes the given Python script file after startup. This option is only available when OVITO has been built with scripting support enabled. Please note that all command line options following the script filename will be passed directly to the Python script and will therefore be ignored by OVITO. |
--nogui | Starts OVITO in console mode and does not show the main window (no graphical user interface). This option only makes sense in conjunction with the --script option to process script files without user interaction. OVITO terminates after executing the script. |
--verbose | Enables the output of additional program information to the console. This can be useful for debugging purposes. |
--nobanner | Suppresses the license information banner printed to the console at startup. |
--help | Shows information about the available command line options and exits. |
--experimental | Enables experimental program features that are still in development. |
OVITO utilizes the OpenGL libraries installed on your system to render a possibly large number of atoms in realtime. Depending on the configuration of your system the OpenGL calls made by OVITO are either executed by a software driver implementation or are passed to the graphics card, which performs high-speed hardware rendering. The latter case is highly recommended, as only hardware rendering enables the display of millions of atoms in realtime. Thus, you should make sure that you have a reasonable graphics card installed and make sure that its OpenGL graphics driver is installed! On a Linux machine you can check this by running the command glxinfo in a console window. It gives a lot of information on the installed OpenGL driver. Check the OpenGL vendor and renderer strings. They should match the installed graphics hardware.
Only newer graphics cards fully support the newest functions of the OpenGL standard. That is why OVITO provides several ways of rendering atoms in the viewport to support older cards, which only implement a subset of the OpenGL functions. You can configure the rendering method in the OVITO settings dialog (choose main menu). These options turn on newer high-performance rendering modes, which are only supported by modern hardware. If you don't see any atoms after importing a data file then you should turn them off, one by one, to fall back to a slower compatibility mode, which might be more appropriate for your graphics card. You may have to restart OVITO to let these settings take effect. You can also start OVITO from a console window to inspect the status output it gives while trying to render atoms.
→ from the