Merge branch 'version-1-fixes' into 'develop'

Version 1.0 release

See merge request educelab/OpenABF!3

Author: csparker247

.gitlab-ci.yml

@@ -31,5 +31,15 @@ test:debian:10:
   image: volcart/vcbuilder-debian:10_v1.static
   variables:
     EXTRA_CMAKE_FLAGS: "-DOPENABF_BUILD_TESTS=ON"
+  tags:
+    - docker
+
+examples:debian:10:
+  extends: .build
+  stage: test
+  needs: []
+  image: volcart/vcbuilder-debian:10_v1.static
+  variables:
+    EXTRA_CMAKE_FLAGS: "-DOPENABF_BUILD_EXAMPLES=ON"
   tags:
     - docker

.zenodo.json

@@ -1,6 +1,6 @@
 {
   "title": "OpenABF",
-  "description": "A header-only library of angle-based flattening algorithms for C++.",
+  "description": "A single-header C++ library of angle-based flattening algorithms.",
   "upload_type": "software",
   "license": "other-open",
   "creators": [
@@ -13,7 +13,8 @@
   "keywords" : [
     "c-plus-plus",
     "parameterization",
-    "flattening"
+    "flattening",
+    "angle-based flattening"
   ],
   "related_identifiers": [
     {

CMakeLists.txt

@@ -62,18 +62,23 @@ install(
 
 # Docs
 find_package(Doxygen OPTIONAL_COMPONENTS dot)
-CMAKE_DEPENDENT_OPTION(OPENABF_BUILD_DOCS "Build Doxygen documentation" on "DOXYGEN_FOUND" off)
+CMAKE_DEPENDENT_OPTION(OPENABF_BUILD_DOCS "Build Doxygen documentation" off "DOXYGEN_FOUND" off)
 if(OPENABF_BUILD_DOCS)
     add_subdirectory(docs)
 endif()
 
+# Examples
+option(OPENABF_BUILD_EXAMPLES "Compile OpenABF example applications" off)
+if(OPENABF_BUILD_EXAMPLES)
+    add_subdirectory(examples)
+endif()
+
 # Tests
 option(OPENABF_BUILD_TESTS "Compile OpenABF unit tests" off)
 if(OPENABF_BUILD_TESTS)
     enable_testing()
     add_subdirectory(tests)
 endif()
 
-# Example app
-add_executable(abf_test main.cpp)
-target_link_libraries(abf_test OpenABF::OpenABF)
+# Install
+include(InstallProject)

CONTRIBUTING.md

@@ -8,7 +8,7 @@ feature requests, and code contributions.
 If you think you have found a bug or if you would like to request a new 
 feature, please check our 
 [issue tracker](https://gitlab.com/educelab/OpenABF/-/issues) to make sure
-an issue has not already been opened on your topic.
+that an issue has not already been opened on your topic.
 
 ## Workflow
 1) Fork this repository
@@ -49,7 +49,7 @@ always process an entire branch's diff by comparing against the default
 branch:
 
 ```shell
-git clang-format dev
+git clang-format develop
 ```
 
 Unfortunately, `clang-format` does not handle all style issues. For a general 
@@ -58,7 +58,7 @@ overview of the EduceLab C++ style, please refer to our
 
 ## License
 Any changes intentionally contributed to this repository are assumed to
-be licensed under the terms outlined in `LICENSE`.
+be licensed under the terms outlined in [LICENSE](LICENSE).
 
 ## Attribution
 This project actively maintains a citable record on Zenodo. 

NOTICE

@@ -1,4 +1,4 @@
-OpenABF
+OpenABF (https://gitlab.com/educelab/OpenABF)
 Copyright 2021 EduceLab
 
 This product includes software developed at

README.md

@@ -1,56 +1,26 @@
 [![OpenABF](docs/images/banner.svg)](https://gitlab.com/educelab/OpenABF)
 
-**OpenABF** is a header-only library of angle-based flattening algorithms for 
-C++. It is designed to be as simple as possible to integrate into existing 
-projects.
+**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.
 
-## Requirements
-* [Eigen 3.3+](http://eigen.tuxfamily.org/)
-
-## Installation
-### CMake
-This project is configured and installed using the CMake build system:
-
-```shell
-mkdir build
-cmake -S . -B build/
-cmake --install build/
-```
-
-This will install the OpenABF header(s) to your default system path and provide 
-an easy method to link OpenABF against your own CMake project:
-
-```cmake
-# Find OpenABF libraries
-find_package(OpenABF REQUIRED)
-
-# Link to an executable
-add_executable(MyTarget main.cpp)
-target_link_libraries(MyTarget OpenABF::OpenABF)
-```
-
-The CMake project provides a number of flags for configuring the installation:
-- `OPENABF_MULTIHEADER`: Install the multi-header version of OpenABF 
-  (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). (Default: ON if Doxygen is found)
-
-### Manual
-Copy and paste the contents of `single_include` to your project or include path. 
-As this project requires Eigen, you also need to add that project to your 
-include path.
+## Dependencies
+- C++14 compiler
+- [Eigen 3.3+](http://eigen.tuxfamily.org/)
+- CMake 3.15+ (optional)
 
 ## Usage
+The following example demonstrates how to construct and parameterize a mesh 
+with OpenABF: 
+ 
 ```c++
 #include <OpenABF/OpenABF.hpp>
 
 // Alias algorithms for convenience
 using ABF = OpenABF::ABFPlusPlus<float>;
 using LSCM = OpenABF::AngleBasedLSCM<float, ABF::Mesh>;
 
-// Make a new mesh
+// Make a triangular pyramid mesh
 auto mesh = ABF::Mesh::New();
 mesh->insert_vertex(0, 0, 0);
 mesh->insert_vertex(2, 0, 0);
@@ -67,36 +37,120 @@ for (const auto& v : mesh->vertices()) {
 }
 
 // Compute parameterized angles
-ABF abf;
-abf.setMesh(mesh);
-abf.compute();
+ABF::Compute(mesh);
 
 // Compute mesh parameterization from angles
-LSCM lscm;
-lscm.setMesh(mesh);
-lscm.compute();
+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](https://gitlab.com/educelab/OpenABF/-/issues/4) 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.
+
+## Installation
+### CMake
+This project can be configured and installed using the CMake build system:
+
+```shell
+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:
+
+```cmake
+# 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](https://cmake.org/cmake/help/latest/module/FetchContent.html):
+
+```cmake
+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`:
+
+```cmake
+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:
+
+```shell
+g++ -I /path/to/eigen/ -DNDEBUG -std=c++14 -O3 main.cpp -o main
+```
+
+**Note:** For best performance, compile your application with the `NDEBUG` 
+preprocessor definition.
 
 ## License
 OpenABF is licensed under [the Apache 2.0 license](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 the [NOTICE](NOTICE).
+the attributions provided in [NOTICE](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](http://creativecommons.org/licenses/by-nc-sa/4.0/).
 
 ## Contributors
-If you would like to fix bugs or develop new features for OpenABF, please see 
-[CONTRIBUTING.md](CONTRIBUTING.md) for more information.
+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](CONTRIBUTING.md) for more information on how to get started.
 
 ### Updating the single-header file
-All code changes should be made to the multi-header library files in 
-`include/OpenABF`. Before your Merge Request can be accepted, yoy need to update 
-the single-header library with your changes by running the following command 
-in the root of the source directory:
+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:
 
 ```shell
 python3 thirdparty/amalgamate/amalgamate.py -c single_include.json -s .
@@ -105,7 +159,7 @@ python3 thirdparty/amalgamate/amalgamate.py -c single_include.json -s .
 ## 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.
+* 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.