Coefficient Flow algorithm

Introduction

This repository imelements the Coefficient_Flow algorithm presented in [1].

Compiling

In order to compile this repository you will need the following packages:

• cmake (v >= 2.8)
• clang (v == 3.8)
• Eigen (v == 3.3.2)
• Boost (v >= 1.54.0)
• Gudhi (v >= 1.3.1)

Running

The timing tests presented in [1] can be run easily by simply performing

mkdir build && cd build
cmake .. && make
make timing_test

this will take a long time to run as it will run a test for a random mesh comprising (about) x 1ey points, with x in [1..9] and y in [1..5]. The results of the test are output to the file results.csv.

For the other tests presented in [1] we only provide the yaml files needed to run them, as the meshes are provided by a third party and can be found in here [2] and here [3]. The aforementioned yaml files are stored in the /test folder and can be run (after the project has been built, and starting from the build directory, and making sure that the proper mesh is located in the same folder)

cp ../test/bunny2.yaml .
./yamltest bunny2.yaml

This will output two ply files which contain a copy of the mesh bunzipper.ply and the bounding chain to the cycle specified by the path contained in the yaml file. One of them was computed by solving a large linear system using least squares conjugate gradient descent, whereas the other was computed by employing coefficient_flow.

Running with docker

A docker file is provided in the Docker folder, and can be built by simply running docker build -t coeff-flow . from the Docker folder. Alternative an image of the same file can be downloaded from docker hub via docker pull crvsf/coeff-flow and there you can run the tests by:

docker run -it crvsf/coeff-flow
cd /coeff-flow build
make timing-test

to run the timing tests, the files for the other tests, are still not provided.

Compiling python bindings

Python bindings will (to the best of my knowledge) be compiled to be compatible with whichever version of python is set as default in the current system, that is if /usr/bin/python points to version 2.7 then python2 bindings will be created, and if it points to version 3.6 python3 bindings will be created. This, to the best of my knowledge is the default behaviour of pybind11.

Using Python bindings

In the python bindings we provide bindings for the simplicial_complex which uses only cells to for construction, and provides also bindings for the functions cell_to_index and index_to_cell. Furthermore we provide bindings for coeff_flow and coeff_flow_embedded. Below is a toy example run:

>>> import coeffflow
>>> a = coeffflow.simplicial_complex([[0,1,2]])
>>> a.cell_to_index([0,2])
1
>>> a.index_to_cell(0,1)
[1]
>>> a.index_to_cell(1,2)
[2, 1]
>>> coeffflow.coeff_flow_embedded(a ,(1, [1,-1,1]))
(2, [1.0])

References/links

[1]: Carvalho JF, Vejdemo-Johansson M, Kragic D, Pokorny FT. An algorithm for calculating top-dimensional bounding chains. 2017 PeerJ Preprints 5:e3151v1

[2]: The Stanford 3D Scanning Repository https://graphics.stanford.edu/data/3Dscanrep/#bunny

[3]: Smithsonian X3D https://3d.si.edu/explorer/eulaema-bee#downloads