xiaotseng/OpenABF

OpenABF is a single-header C++ library of angle-based flattening algorithms. The templated interface is designed for simple out-of-the-box use, and integration with existing geometric processing pipelines is quick and easy.

[[TOC]]

Dependencies

C++14 compiler
Eigen 3.3+
CMake 3.15+ (optional)

Usage

The following example demonstrates how to construct and parameterize a mesh with OpenABF:

#include <OpenABF/OpenABF.hpp>

// Alias algorithms for convenience
using ABF = OpenABF::ABFPlusPlus<float>;
using LSCM = OpenABF::AngleBasedLSCM<float, ABF::Mesh>;

// Make a triangular pyramid mesh
auto mesh = ABF::Mesh::New();
mesh->insert_vertex(0, 0, 0);
mesh->insert_vertex(2, 0, 0);
mesh->insert_vertex(1, std::sqrt(3), 0);
mesh->insert_vertex(1, std::sqrt(3) / 3, 1);

mesh->insert_face(0, 3, 1);
mesh->insert_face(0, 2, 3);
mesh->insert_face(2, 1, 3);

// Print original coordinates
for (const auto& v : mesh->vertices()) {
    std::cout << v->idx << ": " << v->pos << std::endl;
}

// Compute parameterized angles
ABF::Compute(mesh);

// Compute mesh parameterization from angles
LSCM::Compute(mesh);

// Print new coordinates
for (const auto& v : mesh->vertices()) {
    std::cout << v->idx << ": " << v->pos << std::endl;
}

Note: The HalfEdgeMesh class currently assumes that the surface has a boundary, is manifold, and that the winding order of all faces is the same. Care should be taken that this assumption is not violated when constructing your mesh.

Documentation

Visit our full library documentation here.

Installation

CMake

This project can be configured and installed using the CMake build system:

mkdir build
cmake -S . -B build/
cmake --install build/

This will install the OpenABF header(s) to your system include path and provide an easy method for including OpenABF inside of your own CMake project:

# Find OpenABF libraries
find_package(OpenABF REQUIRED)

# Link to an executable
add_executable(MyTarget main.cpp)
target_link_libraries(MyTarget OpenABF::OpenABF)

Note: For best performance, configure your CMake project with the -DCMAKE_BUILD_TYPE=Release flag.

Configuration

The OpenABF CMake project provides a number of flags for configuring the installation:

OPENABF_MULTIHEADER: Install the multi-header version of OpenABF (Default: OFF)
OPENABF_BUILD_EXAMPLES: Build example applications. (Default: OFF)
OPENABF_BUILD_TESTS: Build project unit tests. This will download and build the Google Test framework. (Default: OFF)
OPENABF_BUILD_DOCS: Build documentation. Dependencies: Doxygen, Graphviz (optional). Unavailable if Doxygen is not found. (Default: OFF)

FetchContent (CMake 3.11+)

Another option for providing OpenABF to your project is by using CMake's FetchContent module:

include(FetchContent)
FetchContent_Declare(
  openabf
  GIT_REPOSITORY https://gitlab.com/educelab/OpenABF.git
  GIT_TAG v1.0
)

# Populate the project but exclude from All targets
FetchContent_GetProperties(openabf)
if(NOT openabf_POPULATED)
  FetchContent_Populate(openabf)
  add_subdirectory(${openabf_SOURCE_DIR} ${openabf_BINARY_DIR} EXCLUDE_FROM_ALL)
endif()

This downloads the OpenABF source code and adds it to your CMake project as a subproject. Link it against your targets as you would any library added with find_package:

add_executable(MyTarget main.cpp)
target_link_libraries(MyTarget OpenABF::OpenABF)

Manual

Copy and paste the contents of single_include/ to your project or include path. As OpenABF depends upon the Eigen library, you will also need to add the Eigen headers to your include path:

g++ -I /path/to/eigen/ -std=c++14 -DNDEBUG -O3 main.cpp -o main

Note: For best performance, compile your application with the -DNDEBUG -03 preprocessor definitions.

Contributors

OpenABF is glad to welcome contributors of all skill sets. If you have found a bug or wish to contribute a new feature, please see CONTRIBUTING for more information on how to get started.

Updating the single-header file

OpenABF is deployed as a single-header library, but is developed as a multi-header library. All code changes should be made to the multi-header files in include/OpenABF/. Before your Merge Request can be accepted, please update the single-header file with your changes by running the following command from the root of the source directory:

python3 thirdparty/amalgamate/amalgamate.py -c single_include.json -s .

License

OpenABF is licensed under the Apache 2.0 license. This allows you to use OpenABF freely in open source or proprietary software. However, any software released in source or binary form must include and preserve a readable copy of the attributions provided in NOTICE.

The OpenABF logo and banner graphic are by Seth Parker (EduceLab, University of Kentucky) and are licensed under CC BY-NC-SA 4.0.

Citation

If you use OpenABF in your research, please cite this repository in your publication using our Zenodo record.

References

This project implements data structures and algorithms derived from the following publications:

Alla Sheffer and Eric de Sturler. Parameterization of faceted surfaces for meshing using angle-based flattening. Engineering with Computers, 17(3):326–337, 2001.
Bruno Lévy, Sylvain Petitjean, Nicolas Ray, and Jérome Maillot. Least squares conformal maps for automatic texture atlas generation. ACM Transactions on Graphics (TOG), 21(3):362–371, 2002.
Alla Sheffer, Bruno Lévy, Maxim Mogilnitsky, and Alexander Bogomyakov. Abf++: fast and robust angle based flattening. ACM Transactions on Graphics (TOG), 24(2):311–330, 2005.
S. Marschner, P. Shirley, M. Ashikhmin, M. Gleicher, N. Hoffman, G. Johnson, T. Munzner, E. Reinhard, W.B. Thompson, P. Willemsen, and B. Wyvill. Fundamentals of computer graphics. 4th edition, 2015.

xiaotseng / OpenABF