Directional - A Directional-Field Processing Library¶

https://github.com/avaxman/Directional/

Directional is a C++ library for creating, manipulating and visualizing directional fields on 3D meshes. It is based on both libigl and Eigen. Directional represents directional fields: discrete sets of vectors on meshes. Much of the content and the notations are based on the Eurographics 2016 star (adapted subsequently to SIGGRAPH Asia 2016/SIGGRAPH 2017 courses) on Directional Field Synthesis, Design, and Processing. Some visualization code is borrowed from the libhedra library.

Directional was called “libdirectional” until version 1.5. The name was shortened to avoid a clash with libDirectional.

Installation¶

Directional is a header-only library where each file generally includes one function. To use the library, simply add the include directory to your include path and make sure Directional and its prerequisites are set up properly. After that you can include any files you need normally, using for example #include <directional/index_prescription.h>.

To get the library, simply clone the repository using:

git clone --recursive https://github.com/avaxman/Directional.git


Features¶

The current version is 1.7, comprising the following features:

1. Representation of per-face directional fields of any given degree and symmetry.
2. Visualization of fields using (sparsified) glyphs and streamline tracing.
3. Principal and curl matching, and combing for $N$-directional fields.
4. Computation of power fields of $N$-RoSy fields.
5. PolyVector fields.
6. Optimization for curl reduction.
7. Conjugate fields.
8. Prescription of singularity, generator, and boundary indices.
9. Rotationally- and fully-seamless integration of branched $N$-functions.
10. Meshing of the arrangement of $N$-functions isolines into polygonal meshes.
11. Subdivision fields.

Directional is a header-only library. You do not need to compile anything to use, just include directional headers (e.g. #include <directional/index_prescription.h>) and run. Each header file contains a single function (e.g. igl/index_prescription.h contains igl::index_prescription()). Nevertheless, the meshing packages requires CGAL, which is facilitated using the libigl interface.

Tutorial¶

A Tutorial that walks through the entire functionality of Directional is available. To compile it, go to the tutorial folder, open a shell and call:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ../
make

This should properly set up the tutorial project, with the individual chapters as subprojects, and create project makefiles upon which you can build it using your favourite compiler. For windows, we recommend to use cmake-gui .. and follow the instructions to create a compilable Visual Studio file.

Coding Guidelines and Tips¶

Directional inherits and follows the strict coding guidelines of libigl: please take a look here before submitting your pull requests.

How to Contribute¶

Directional is primarily MPL2 licensed (FAQ). Some files contain third-party code under other licenses.

If you use Directional in your academic projects, please cite the implemented papers directly, and/or the EG STAR 2016 when appropriate. To cite the library in general, you could use this BibTeX entry:

@misc{Directional,
author       = {Amir Vaxman and others},
title        = {{Directional: A library for Directional Field
Synthesis, Design, and Processing}},
doi          = {10.5281/zenodo.3338174},
url          = {https://doi.org/10.5281/zenodo.3338174}
}


Contact¶

If you’re using Directional in your projects, quickly drop me a note. Tell me who you are and what you’re using it for. This helps justify spending time maintaining this library!

Future Plans¶

The following functionality is still in workds for Directional. Please contact me for any suggestions or contributions from this wish list which are very welcome!

1. Other discretizations: discrete exterior calculus, vertex-based fields.
2. 3D fields.
3. Discrete vector calculus: operators and Hodge decomposition.
4. Line-integral convolution visualization.

If you would like to suggest further topics, would like to collaborate in implementation, complain about bugs or ask questions, please address Amir Vaxman (or open an issue in the repository).

2017 Amir Vaxman, Sam de Redelijkheid, Daniele Panozzo, Olga Diamanti, Olga Sorkine-Hornung, and others.