Correrender is a correlation field volume renderer using the graphics API Vulkan.
There are four ways to build the program on Linux systems.
- Using the system package manager to install all dependencies (tested: apt on Ubuntu, pacman on Arch Linux, dnf/yum on Fedora).
- Using vcpkg to install all dependencies (by using the flag
./build.sh --vcpkg). - Using conda to install all dependencies (by using the flag
./build.sh --conda). - Using Nix to install all dependencies (by invoking
./build.shafter callingnix-shell).
The script build.sh in the project root directory can be used to build the project. If no arguments are passed, the
dependencies are installed using the system package manager. When calling the script as ./build.sh --vcpkg, vcpkg is
used instead. The build scripts will also launch the program after successfully building it. If you wish to build the
program manually, instructions can be found in the directory docs/compilation.
Below, more information concerning different Linux distributions tested can be found.
Arch Linux and its derivative Manjaro are fully supported using both build modes (package manager and vcpkg).
The Vulkan SDK, which is a dependency of this program that cannot be installed using vcpkg, will be automatically
installed using the package manager pacman when using the scripts.
Ubuntu 22.04 is fully supported.
The Vulkan SDK, which is a dependency of this program that cannot be installed using the default package sources or vcpkg, will be automatically installed using the official Vulkan SDK PPA.
Please note that Ubuntu 18.04 and 20.04 ship a too old version of CMake, which causes the build process to fail. In this case, CMake needs to be upgraded manually beforehand using the steps at https://apt.kitware.com/.
If you are using a different Linux distribution and face difficulties when building the program, please feel free to open a bug report. In theory, the build scripts should also work on other Linux distributions as long as the Vulkan SDK is installed manually beforehand.
The program can use CUDA to enable optional features. If the build scripts are not able to find your CUDA installation
on Linux, add the following lines to the end of $HOME/.profile and log out of and then back into your user account.
cuda-12.1 needs to be adapted depending on the CUDA version installed. On distributions other than Ubuntu and Debian,
like Arch Linux and Manjaro, the library path may be different from the one below, e.g., /usr/local/cuda-12.1/lib64.
export CPATH=/usr/local/cuda-12.1/targets/x86_64-linux/include:$CPATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.1/targets/x86_64-linux/lib:$LD_LIBRARY_PATH
export PATH=/usr/local/cuda-12.1/bin:$PATHThere are two ways to build the program on Windows.
- Using vcpkg to install the dependencies. The program can then be compiled using Microsoft Visual Studio.
- Using MSYS2 to install the dependencies and compile the program using MinGW. In this case, all CUDA interoperability features are disabled. Currently, the CUDA compiler nvcc only supports MSVC on Windows.
In the project folder, a script called build-msvc.bat can be found automating this build process using vcpkg and
Visual Studio. It is recommended to run the script using the Developer PowerShell for VS 2022 (or VS 2019 depending on
your Visual Studio version). The build script will also launch the program after successfully building it.
Building the program is regularly tested on Windows 10 and 11 with Microsoft Visual Studio 2019 and 2022.
Please note that the Vulkan SDK needs to be installed beforehand if using Microsoft Visual Studio for compilation.
The script build.sh in the project root directory can also be used to alternatively build the program using
MSYS2/MinGW on Windows. For this, it should be run from a MSYS2 shell.
If you wish to build the program manually using Visual Studio and vcpkg, or using MSYS2, instructions can be found in
the directory docs/compilation.
Under Data/VolumeDataSets/datasets.json, loadable volume data sets can be specified. Additionally, the user can also
open arbitrary data sets using a file explorer via "File > Open Dataset..." (or using Ctrl+O).
Below, an example for a Data/VolumeDataSets/datasets.json file can be found.
{
"datasets": [
{ "name" : "Karman Vortex Street", "filename": "data/vortex_street.nc" },
{ "type" : "Rotated Data", "filename": "data/other_data.dat", "transform": "rotate(270°, 1, 0, 0)" },
{ "type" : "Time Dependent Data", "filename": "data/data_timestep_%04i.dat", "time_indices": "0 2500 10" }
]
}These files then appear with their specified name in the menu "File > Datasets". All paths must be specified relative to
the folder Data/VolumeDataSets/ (unless they are global, like C:/path/file.dat or /path/file.dat).
Supported formats currently are:
- .nc (NetCDF format, https://www.unidata.ucar.edu/software/netcdf/).
- .zarr (Zarr format, https://zarr.readthedocs.io/en/stable/).
- .grb/.grib (GRIB format, https://weather.gc.ca/grib/what_is_GRIB_e.html).
- .vtk (structured grids in VTK format).
- .vti, .vts (structured grids in VTK XML format).
- .am (AmiraMesh format, see https://www.csc.kth.se/~weinkauf/notes/amiramesh.html).
- The custom .field, .bin, .dat and .raw file formats used in our research group.
This repository takes part in the Graphics Replicability Stamp Initiative (GRSI).
For more information, please refer to replicability/README.md.
For more details on the Replicability Stamp itself, please refer to http://www.replicabilitystamp.org/.
When reporting a bug, please also attach the logfile generated by Correrender. Below, the location of the logfile on different operating systems can be found.
- Linux:
~/.config/correrender/Logfile.html - Windows:
%AppData%/Correrender/Logfile.html(i.e.,C:/Users/<USER>/AppData/Roaming/Correrender/Logfile.html) - macOS:
~/Library/Preferences/Correrender/Logfile.html