Installation Instructions - Linux

Ubuntu Fresh Install

Installation List

sudo apt install git cmake xorg-dev freeglut3-dev build-essential

Python Bindings

If you plan on using the python bindings by specifying -DUSE_PYTHON_BINDINGS=On, then you should also have a working python installation in your path. This installs an additional tool pipx, which allows the installation of packages as executables in virtualized environments.

sudo apt install python3-dev python3-pip python3-venv
python3 -m pip install pipx
python3 -m pipx ensurepath

Alternatively to this you may also install other Python Distributions such as Anaconda (personal preference).

Building Instructions

git clone https://github.com/InteractiveComputerGraphics/SPlisHSPlasH.git
cd SPlisHSPlasH
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DUSE_PYTHON_BINDINGS=<On|Off> ..
make -j 4

Run Executable

cd ../bin
./SPHSimulator ../data/Scenes/DoubleDamBreak.json

On some systems it may be necessary to define an OpenGL override like so

cd ../bin
MESA_GL_VERSION_OVERRIDE=3.3 ./SPHSimulator ../data/Scenes/DoubleDamBreak.json

The command loads the selected scene. To start the simulation disable the pause mode by clicking the checkbox or pressing [Space]. More hotkeys are listed here.

Using Bindings

Assuming that the python bindings were generated in the default location Project Root/build/lib/pysplishsplash.cpython-38-x86_64-linux-gnu.so, you can use the bindings by adding this path to sys.path within your python script, or by calling your scripts within the directory containing the .so file. You can test that the bindings work using the following command.

cd lib
python3 -c "import pysplishsplash"

Installing Bindings

If you followed the above instructions for building SPlisHSPlasH using CMake and generated the python bindings, then these commands should work automatically.

Note: You don’t have to clone the repository again. This only shows, that the command should be run in the project root directory. It is also recommended, that you create and activate a virtual environment before installing, so that your base python installation is not affected by any new generated files.

git clone https://github.com/InteractiveComputerGraphics/SPlisHSPlasH.git
cd SPlisHSPlasH
python setup.py bdist_wheel
pip install build/dist/*.whl

If you specified any additional CMake variables in the form of -DVAR_NAME=Value, you can just append them after bdist_wheel

Alternatively you may also run the following command, which essentially combines all of the above commands into a single command.

pip install git+https://github.com/InteractiveComputerGraphics/SPlisHSPlasH.git

Drawbacks: You lose the ability for incremental rebuilds, i.e. if you want to modify the source code and build the bindings anew, you would have to build the entire project every time.

Installation Instructions - Windows

Visual Studio

Dependencies

To build SPlisHSPlasH on Windows you need to install CMake and git.

Python Bindings

If you plan on using the python bindings by specifying -DUSE_PYTHON_BINDINGS=On, then you should also have a working Python installation in your path. Moreover, you require the Python Package Installer (pip).

Building Instructions

First, clone the repository by

git clone https://github.com/InteractiveComputerGraphics/SPlisHSPlasH.git

Then run cmake-gui and set “Where is the source code:” to the [SPlisHSPlasH-dir] and “Where to build the binaries:” to [SPlisHSPlasH-dir]/build.

Now run Configure and select the correct Visual Studio version. Ensure that you choose a x64 build on a 64bit system. Finally, run Generate and open the project. Now you can build the project in Visual Studio. Note that you have to select the “Release” build, if you want to have an optimized executable.

Run Executable

Execute “bin/SPHSimulator.exe” to start the simulator and select a scene file to run the simulation. Alternatively, you can start the simulation in the command line:

./SPHSimulator ../data/Scenes/DoubleDamBreak.json

The command loads the selected scene. To start the simulation disable the pause mode by clicking the checkbox or pressing [Space]. More hotkeys are listed here.

Using Bindings

Assuming that the python bindings were generated in the default location [SPlisHSPlasH-dir]/build/lib/pysplishsplash.cp37-win_amd64.pyd, you can use the bindings by adding this path to sys.path within your python script, or by calling your scripts within the directory containing the .pyd file. You can test that the bindings work using the following command.

cd lib
python3 -c "import pysplishsplash"

Installing Bindings

If you followed the above instructions for building SPlisHSPlasH using CMake and generated the python bindings, then these commands should work automatically.

Note: You don’t have to clone the repository again. This only shows, that the command should be run in the project root directory. It is also recommended, that you create and activate a virtual environment before installing, so that your base python installation is not affected by any new generated files.

git clone https://github.com/InteractiveComputerGraphics/SPlisHSPlasH.git
cd SPlisHSPlasH
python setup.py bdist_wheel
pip install build/dist/pySPlisHSPlasH-2.8.3-cp37-cp37m-win_amd64.whl

If you specified any additional CMake variables in the form of -DVAR_NAME=Value, you can just append them after bdist_wheel

Alternatively you may also run the following command, which essentially combines all of the above commands into a single command.

pip install git+https://github.com/InteractiveComputerGraphics/SPlisHSPlasH.git

Drawbacks: You lose the ability for incremental rebuilds, i.e. if you want to modify the source code and build the bindings anew, you would have to build the entire project every time.