This repository contains C++ code for our paper "Repulsive Shells" published at SIGGRAPH 2024 by Josua Sassen, Henrik Schumacher, Martin Rumpf, and Keenan Crane. Specifically, it contains code to compute geodesics, the exponential map, and weighted geodesic means on the Shape Space of Repulsive Shells. Furthermore, data and configurations demonstrating these concepts on a set of examples are included as well.

The code is based on GOAST 👻 a C++ library for research in Geometry Processing focused on variational approaches. Thus, it inherits its dependencies and adds a few additional ones (see below). If you should have any questions, feel free to reach out!

NOTE: So far, this code has only been tested on Linux, specifically Ubuntu, and macOS. Tests on further operating systems are planned, but until then, the instructions below might be incomplete. Again, if you should run into trouble, please reach out even if you have resolved the issues so we can adapt these instructions.

We split the necessary dependencies for our code into ones that are included in this repository (directly or as git submodule) and ones that users needs to install on their own beforehand:

• GOAST 👻 (as git submodule)
• an earlier version of Repulsor as efficient tangent-point implementation (directly)
• PQP for triangle-triangle distances (directly)
• yaml-cpp for configuration files (git submodule)

• OpenMesh
• Eigen
• SuiteSparse
• Boost
• VTK is optional but provides more output

This repository includes git submodules, which means to clone the repository one has to use either

git clone https://github.com/jrsassen/repulsive-shells.git 
cd repulsive-shells # or which ever folder you cloned the project to
git submodule init # initialize submodules given in .gitmodules
git submodule update # clone submodules

or, more compactly,

git clone --recurse-submodules https://github.com/jrsassen/repulsive-shells.git

For a detailed explanation of git submodules, see for example the git book.

The project is compiled using the common CMake routine:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --config Release

Depending on how one installed the external dependencies this might not find all of them. In this case, one needs to tell CMake where they are explicitly by setting the following options.

The following additional CMake options might also be interesting:

Setting these options can be achieved by specifying them in the terminal in the following way

cmake -D<OPTION>=<VALUE> ..

or by using cmake-gui.

After building, a number of executables should be present in the build directory that can be run typically with paths to YAML configuration files as commandline argument. Here is a list of these executables, what they do, and if/which configuration examples are provided (in the data folder).

Executables take paths to YAML configuration files as commandline arguments. For example configurations, see the data folder. Please note, that the paths specified in these example configurations expect (a) that one runs the exectuables in the main directory of the repository, and (b) one creates a folder called output first.

This code includes and uses two implementations of the discrete adaptive tangent-point energy proposed in our paper.

On the one hand, there is an implementation by Henrik, which is essentially an earlier version of the Repulsor library. This implementation focuses on efficiency and thus, e.g., exploits the vectorization capabilities of modern CPUs. In the code and configuration files, it is dubbed ScaryTPE and it is the implementation that has been used for the examples shown in our paper and, generally, is the recommended one.

On the other hand, there is an implementation by Josua that is focused on readability over performance and is mostly meant as additional illustration for the implementation notes and pseudocode provided in our paper. Note that it differs from the former implementation in a few places, which might have a small impact on results. In the code and configuration files, it is dubbed SpookyTPE. As a small warning, even though focused on readability, the code is not 100% cleaned up and could certainly be improved!

The code (except for the included dependencies) is provided under the MIT license (see the LICENSE file). For the licenses of the included open source dependencies, please take a look at the corresponding subfolders in the deps folder.

If you use this code or our work in general in a research paper, please remember to cite our paper! You can use the following bibtex:

@article{SaScRu24,
    author = {Sassen, Josua and Schumacher, Henrik and Rumpf, Martin and Crane, Keenan},
    title = {{Repulsive Shells}},
    year = {2024},
    issue_date = {July 2024},
    publisher = {Association for Computing Machinery},
    address = {New York, NY, USA},
    volume = {43},
    number = {4},
    issn = {0730-0301},
    doi = {10.1145/3658174},
    journal = {ACM Transaction on Graphics},
    articleno = {140},
    numpages = {22}
}