Installation¶

Option 1: Pre-built Docker container¶

Install Docker.
docker run nilsleiffischer/gwpv:latest

Try rendering one of the example scenes:

docker run -v $PWD:/out nilsleiffischer/gwpv:latest \
  scene Examples/Rainbow/Still.yaml -o /out

Docker will pull the latest pre-built image and run it. The container runs the gwrender entrypoint automatically (see Usage).

To output rendered frames and load data from your system you can mount directories using Docker’s -v option. In the example above we mount the current working directory $PWD as the directory /out in the container and use it to output frames. You can mount additional directories to make your scene configuration files and data available in the container (see Usage).

Option 2: Native environment¶

Install ParaView (v5.10 or above). You can download a pre-built binary or use Spack to configure a build to your liking and compile it from source. Make sure to install ParaView with support for Python 3.
Create a virtual environment with ParaView’s Python. You could do this:
```
path/to/python3 -m venv path/to/new/env
```
Make sure to set up the environment with the same Python installation that ParaView uses. If you are unsure, try this:
```
# Start interactive ParaView Python shell
path/to/pvpython
# Output path to the Python executable
>>> import sys
>>> sys.executable
```
On macOS the pvpython executable is typically located in /Applications/ParaView-X.Y.Z.app/Contents/bin. The Python executable determined by the script above may be named vtkpython, in which case you can look for the python3 executable in the same directory or a bin subdirectory. If you can’t find ParaView’s Python executable, try using a Python installation with the same version as ParaView’s.
Give ParaView access to the environment. If you have created the environment with Python 3’s venv then copy the scripts/activate_this.py script to the environment:
```
cp scripts/activate_this.py path/to/new/env/bin
```
Note that environments created with the virtualenv package include this script automatically and you don’t need to copy it. The script is used to activate the environment from within Python scripts. It allows ParaView’s Python to pick up the packages installed in the environment (see this blog post for details).

You may also want to add the ParaView executables such as pvpython to your PATH when the environment is activated for convenient access. To do so you can append the following line to path/to/env/bin/activate as well:
```
export PATH="path/to/paraview/bin/:$PATH"
```
On macOS you may also need to append this line to pick up the paraview GUI executable:
```
export PATH="path/to/paraview/MacOS/:$PATH"
```
Install the following packages in the environment, making sure to use ParaView’s HDF5 when installing h5py:
```
. env/bin/activate
HDF5_DIR=path/to/paraview/hdf5/ pip install --no-binary=h5py h5py
pip install [-e] path/to/this/repository
```
Note that the HDF5_DIR should have include and lib directories with ParaView’s HDF5. On macOS it is typically /Applications/ParaView-X.Y.Z.app/Contents/. Add the -e flag when installing this repository’s Python package to install it in “editable” mode, i.e. symlink instead of copy it so changes to the repository are reflected in the installation.