The pmp-library is a modern C++ open-source library for digital geometry
-processing. It provides a set of geometric data structures frequently used
-in geometry processing tasks as well as implementations of canonical
-algorithms. It has been designed and implemented with a focus on ease of
-use and performance while maintaining high flexibility.
-
-## Quickstart
-
-Fetch the repository:
-
- $ git clone --recursive https://github.com/pmp-library/pmp-library.git
-
-Configure and build:
-
- $ cd pmp-library && mkdir build && cd build && cmake .. && make
-
-See the [installation guide](docs/installation.md) file for more
-detailed installation instructions.
-
-## License
-
-The pmp-library is provided under a flexible 3-clause
-BSD [license](./LICENSE.txt), thereby allowing for both open-source and
-commercial usage.
+processing. See the [home page](http://pmp-library.github.io/pmp-library/) for
+details.
diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in
index a01ac1f..5dd473e 100644
--- a/docs/Doxyfile.in
+++ b/docs/Doxyfile.in
@@ -425,7 +425,7 @@ CASE_SENSE_NAMES = NO
# will show members with their full class and namespace scopes in the
# documentation. If set to YES the scope will be hidden.
-HIDE_SCOPE_NAMES = NO
+HIDE_SCOPE_NAMES = YES
# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
# will put a list of the files that are included by a file in the documentation
@@ -878,7 +878,7 @@ HTML_FILE_EXTENSION = .html
# have to redo this when upgrading to a newer version of doxygen or when
# changing the value of configuration settings such as GENERATE_TREEVIEW!
-HTML_HEADER =
+HTML_HEADER = ${CMAKE_CURRENT_SOURCE_DIR}/header.html
# The HTML_FOOTER tag can be used to specify a personal HTML footer for
# each generated HTML page. If it is left blank doxygen will generate a
@@ -912,7 +912,7 @@ HTML_EXTRA_STYLESHEET = ${CMAKE_CURRENT_SOURCE_DIR}/style.css
# files. In the HTML_STYLESHEET file, use the file name only. Also note that
# the files will be copied as-is; there are no commands or markers available.
-HTML_EXTRA_FILES =
+HTML_EXTRA_FILES = ${CMAKE_CURRENT_SOURCE_DIR}/images/favicon.ico
# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output.
# Doxygen will adjust the colors in the style sheet and background images
diff --git a/docs/codingstyle.md b/docs/codingstyle.md
new file mode 100644
index 0000000..f067947
--- /dev/null
+++ b/docs/codingstyle.md
@@ -0,0 +1,124 @@
+# Coding Style {#codingstyle}
+
+If you would like to contribute to the pmp-library please make sure your source
+code adheres to the following coding conventions. Please use
+the [clang-format](https://clang.llvm.org/docs/ClangFormat.html) tool and the
+corresponding `.clang-format` configuration file from the repository to properly
+format your code.
+
+## Naming
+
+### Types
+
+The names of user-defined types such as classes, structs and enums use
+`CamelCase` notation. The names of persons such as Cholesky or Delaunay are
+properly capitalized as well.
+
+~~~~{.cpp}
+ class PolyLine { ... };
+ enum RGBColors { red, green, blue };
+ class SparseCholeskySolver { ... };
+~~~~
+
+### Functions
+
+Function names are written using `camelCase` notation starting with a lowercase
+letter.
+
+~~~~{.cpp}
+ class ExampleClassName
+ {
+ double exampleFunctionName(void);
+ };
+~~~~
+
+### Variables
+
+Variables are named in `camelCase` notation. Class member variables are prefixed
+with `m_`.
+
+~~~~{.cpp}
+ int globalsConsideredHarmful;
+
+ class ExampleClass
+ {
+ protected:
+ double m_memberVariable;
+ static double m_staticVariable;
+ };
+~~~~
+
+### File Names
+
+File names follow the naming rules for user-defined types. Implementation files
+end with `.cpp` and header files end with `.h`.
+
+## Formatting
+
+### Blocks
+
+The expressions following an `if, else, while, do ... while` or `for` statement
+should always be enclosed in braces. The braces enclosing a block should be
+placed in the same column, on separate lines.
+
+~~~~{.cpp}
+ if (fooBar == baz)
+ {
+ std::cout << "hurz" << std::endl;
+ }
+ else
+ {
+ std::cout << "asdf" << std::endl;
+ }
+~~~~
+
+### Comments
+
+Use C++-style comments, i.e., `// My important comment.` Use `//!` for doxygen
+special comments.
+
+### Line Length
+
+Lines should not exceed more than 80 characters. There should only be one
+statement per line.
+
+### Indentation
+
+Use spaces instead of tabs. Indent the code by four spaces for each
+level of indentation. Avoid trailing whitespaces at the end of a
+line as well as on empty lines.
+
+## Miscellaneous
+
+This section describes some basic programming conventions developers should
+adhere to.
+
+- Use the \#pragma once compiler directive at the beginning of each
+ header file in order to protect against multiple inclusion.
+
+- Use the `pmp` namespace in order to avoid conflicts. In source files, do not
+ add an additional level of indentation due to the namespace:
+
+~~~~{.cpp}
+ namespace pmp {
+
+ class ExampleClass
+ {
+ ...
+ };
+
+ }
+~~~~
+
+- Use meaningful prefixes for `bool` variables or functions returning booleans,
+ e.g., `hasColors()` or `isDone`.
+- Consistently name dynamic properties, e.g., "v:scalar" for vertex scalars or
+ "f:normal" for face normals.
+- Consistently name iterators and circulators by their type
+- Use `std::size_t` where appropriate, e.g., storing values from STL functions
+ such as the `size()` member function of a `std::vector`
+- Localize variable scope and avoid declaring all variables at the beginning of
+ a function or code block.
+- In case you want to preserve the special formatting of a particular code block
+ such as a matrix intialization add the `// clang-format off` and
+ `// clang-format on` directives around this block.
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 0000000..8e6ced2
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,52 @@
+# Contributing {#contributing}
+
+Contributions to the pmp-library are generally welcome. However, please keep in
+mind that we develop the library besides our daily jobs and therefore might not
+always find the time to quickly react to your requests and suggestions.
+
+## Reporting Issues
+
+In case you run into trouble using the pmp-libray, please check for
+existing [issues](https://github.com/pmp-library/pmp-library/issues). If your
+problem is not already reported file a new issue and also provide some piece of
+code and data to reproduce the behavior in question.
+
+## Contributing Code
+
+If you would like to contribute to the development of the pmp-library you should
+start by [forking](https://help.github.com/articles/fork-a-repo) and creating
+a [pull request](https://help.github.com/articles/creating-a-pull-request). Make
+sure that your code follows the [Coding Style](coding_style.html) guidelines. In
+case you want to contribute a new algorithm make sure the code is properly
+documented using doxygen and is accompanied by a unit test, see below.
+
+## Unit Testing
+
+The pmp-library has a suite of unit tests that aims at making sure everything
+works as expected. The unit tests are written
+using [Google Test](https://github.com/google/googletest) and run during
+continuous integration builds. See the also the `tests` sub-directory of the
+repository. You can locally run the test suite from your build directory by
+invoking the
+
+ $ make test
+
+target. To obtain more detailed test output we recommend to invoke the Google
+Test runner directly:
+
+ $ cd tests
+ $ ./gtest_runner
+
+
+## Code Coverage
+
+We track the overall code coverage rate of our unit tests
+using [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html), which is part
+of [GCC](https://gcc.gnu.org/). To check the code coverage locally run
+
+ $ make coverage
+
+This will run the test suite and collect the coverage data. A HTML report of the
+results will be generated to `coverage/index.html`. We generally try to maintain
+a high coverage rate of above 90%. Any code that you would like to contribute
+should not decrease the coverage rate.
diff --git a/docs/development.md b/docs/development.md
deleted file mode 100644
index a915127..0000000
--- a/docs/development.md
+++ /dev/null
@@ -1,118 +0,0 @@
-# Development {#development}
-
-[TOC]
-
-# Contribution Guidelines {#contribution}
-
-- criteria
-- git best practices
-- how to submit
-
-# Testing and Code Coverage {#testing}
-
-- how to write tests
-
-# Coding Conventions {#codingConventions}
-
-If you would like to contribute to pmp please make sure
-your code adheres to the following coding conventions.
-
-## Naming {#naming}
-
-### Types {#types}
-
-The names of user-defined types such as classes, structs and enums use
-`CamelCase` notation. This applies to acronyms as well. The names of persons
-such as Cholesky or Delaunay are properly capitalized as well.
-
- class PolyLine { ... };
- enum RgbColors { red, green, blue };
- class SparseCholeskySolver { ... };
-
-### Functions {#functions}
-
-Function names are written using `camelCase` notation.
-
- class ExampleClassName
- {
- double exampleFunctionName(void);
- };
-
-### Variables {#variables}
-
-Variables are named in `camelCase` notation. Class member
-variables are prefixed with `m_`.
-
- int globalsConsideredHarmful;
-
- class ExampleClass
- {
- protected:
- double m_memberVariable;
- static double m_staticVariable;
- };
-
-### File Names {#fileNames}
-
-File names follow the naming rules for user-defined types. Implementation files
-end with `.cpp` and header files end with `.h`.
-
-## Formatting {#formatting}
-
-### Blocks {#blocks}
-
-The expressions following an `if, else, while, do ... while` or `for` statement
-should always be enclosed in braces. The braces enclosing a block should be
-placed in the same column, on separate lines.
-
- if (fooBar == baz)
- {
- std::cout << "hurz" << std::endl;
- }
- else
- {
- std::cout << "asdf" << std::endl;
- }
-
-### Comments {#comments}
-
-C++-style comments should be used, i.e., `// My important comment.`
-
-### Line Length {#lineLength}
-
-Lines should not exceed more than 80 characters. There should only be one
-statement per line.
-
-### Indentation {#indentation}
-
-Use spaces instead of tabs. Indent the code by four spaces for each
-level of indentation. Avoid trailing whitespaces at the end of a
-line as well as on empty lines.
-
-## Misc {#misc}
-
-This section describes some basic programming conventions developers should
-adhere to.
-
-- Use the \#pragma once compiler directive at the beginning of each
- header file in order to protect against multiple inclusion.
-
-- Use the `pmp` namespace in order to avoid conflicts. In source files, do not
- add an additional level of indentation due to the namespace:
-
- namespace pmp {
-
- class ExampleClass
- {
- ...
- };
-
- }
-
-- use is and has prefixes for boolean predicates
-- consistent property naming
-- consistent iterator / circulator naming
-- using size_t where approriate
-- localized variable scope
-- const auto
-- clang-format on / off
diff --git a/docs/footer.html b/docs/footer.html
index e662fae..4fb2a1d 100644
--- a/docs/footer.html
+++ b/docs/footer.html
@@ -1,5 +1,4 @@
Copyright © 2017 The pmp-library developers diff --git a/docs/header.html b/docs/header.html new file mode 100644 index 0000000..836bfe6 --- /dev/null +++ b/docs/header.html @@ -0,0 +1,56 @@ + + + + + + + +
+
+
+ ..
-# Build Options {#build_options}
+## Build Options
-By default, pmp uses 32-bit unsigned integers as internal index type to
-reference entities. However, if you need to process very large data sets this
+By default, the pmp-libray uses 32-bit unsigned integers as internal index type
+to reference entities. However, if you need to process very large data sets this
might not be sufficient. In this case, you can change the index type to be
64-bit by specifying
diff --git a/docs/mainpage.md b/docs/mainpage.md
index 79fadc2..b7f0ddc 100644
--- a/docs/mainpage.md
+++ b/docs/mainpage.md
@@ -1,20 +1,40 @@
-# User Manual {#mainpage}
+# Introduction {#mainpage}
The pmp-library is a modern C++ open-source library for digital geometry
processing. It provides a set of geometric data structures frequently used
in geometry processing tasks as well as implementations of canonical
algorithms. It has been designed and implemented with a focus on ease of
-use and performance while maintaining high flexibility.
+use and performance while maintaining high flexibility. In addition, it provides
+mesh viewers and visualization utilities based on OpenGL® as well as the
+possibility to compile the library into JavaScript
+using [emscripten](https://github.com/kripken/emscripten).
-This manual is organized into the following sections:
+The [User Guide](./userguide.html) describes how to
+quickly [get started](./quickstart.html) using the pmp-library, provides
+an [overview](./overview.html) of the library and its capabilities,
+a [tutorial](./tutorial.html) as well as guidelines
+for [contributing](./contributing.html) patches or new code.
-- @subpage installation -- How compile and install pmp
-- @subpage quickstart -- How easily to setup your own project using pmp
-- @subpage overview -- An overview of the library components
-- @subpage development -- Guidelines for pmp development and contributions
+The [Reference Documentation](./annotated.html) provides detailed information on
+the classes and functions provided by the pmp-library.
-The [Reference Manual](./annotated.html) provides detailed information on the
-classes and functions provided by pmp.
+## License
+
+The pmp-library is provided under a flexible 3-clause BSD
+[license](https://github.com/pmp-library/pmp-library/blob/master/LICENSE.txt),
+thereby allowing for both open-source and commercial usage.
+
+## Acknowledgment
+
+If you are using the pmp-library for research projects, please acknowledge its
+use by referencing
+
+ @misc{pmp-library,
+ title = {The Polygon Mesh Processing Library},
+ author = {Daniel Sieger and Mario Botsch},
+ note = {http://pmp-library.github.io/pmp-library/},
+ year = {2017},
+ }
## Heritage
diff --git a/docs/overview.md b/docs/overview.md
index c90317f..e4f2e03 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -1,137 +1,55 @@
# Overview {#overview}
-[TOC]
-
-# Introduction {#introduction}
-
-In general, a polygonal surface mesh is composed of vertices, edges and faces as
-well as the incidence relationships between them. SurfaceMesh stores the
-connectivity information based on halfedges, i.e., pairs of directed edges with
-opposing direction. To be more precise:
-
-- Each vertex stores an outgoing halfedge.
-- Each face stores an incident halfedge.
-- Each halfedge stores its incident face, its target vertex, and its previous
- and next halfedges within the face.
-
-The halfedge connectivity is illustrated in the figure below:
-
-
-
-In the following sections we describe the basic usage of SurfaceMesh by means of
-simple example programs and code excerpts.
-
-# Basics {#basics}
-
-The very basic usage of SurfaceMesh is demonstrated in the example below. The
-program first instantiates a SurfaceMesh object as well as four vertex
-handles. These handles, as well as the handles for the other mesh entities
-`Halfedge`, `Edge` and `Face` basically indices. Four vertices are added to the
-mesh, as well as four triangular faces composing a tetrahedron. Finally, the
-number of vertices, edges, and faces is printed to standard output.
-
-\snippet SurfaceMeshBasics.cpp basics
-
-# File I/O {#fileio}
-
-SurfaceMesh currently supports reading OFF, OBJ, and STL files. Write support is
-currently limited to OFF files. All I/O operations are handled by the
-pmp::SurfaceMesh::read() and pmp::SurfaceMesh::write() member functions, with
-the target file name being their only argument. An example is given below.
-
-\snippet SurfaceMeshIO.cpp io
-
-
-# Iterators and Circulators {#iterators}
-
-In order to sequentially access mesh entities SurfaceMesh provides iterators for
-each entity type, namely pmp::PointSet::VertexIterator,
-pmp::EdgeSet::HalfedgeIterator, pmp::EdgeSet::EdgeIterator, and
-pmp::SurfaceMesh::FaceIterator. Similar to iterators, SurfaceMesh also provides
-circulators for the ordered enumeration of all incident vertices, halfedges, or
-faces around a given face or vertex. The example below demonstrates the use of
-iterators and circulators for computing the mean valence of a mesh.
-
-\snippet SurfaceMeshIterators.cpp iterators
-
-# Dynamic Properties {#properties}
-
-Attaching additional attributes to mesh entities is important for many
-applications. SurfaceMesh supports properties by means of synchronized
-arrays that can be (de-)allocated dynamically at run-time. Property arrays
-are also used internally, e.g., to store vertex coordinates. The example
-program below shows how to access vertex coordinates through the
-(pre-defined) point property.
-
-\snippet SurfaceMeshBarycenter.cpp barycenter
-
-The dynamic (de-)allocation of properties at run-time is managed by a set
-of four different functions:
-
-- add[_EntityType_]Property<_PropertyType_>(_PropertyName_) allocates a new
- property for the given _EntityType_ of the type _PropertyType_ labeled by the
- _PropertyName_ string.
-- get[_EntityType_]Property<_PropertyType_>(_PropertyName_) returns a handle
- to an existing property.
-- _EntityType_Property<_PropertyType_>(_PropertyName_) returns a handle to
- an existing property if the specified property already exists. If not, a new
- property is allocated and its handle is returned.
-- remove[_EntityType_]Property(_PropertyHandle_) removes and the vertex
- property referenced by _PropertyHandle_.
-
-Functions that allocate a new property take a default value for the property as
-an optional second argument. The code excerpt below demonstrates how to
-allocate, use and remove a custom edge property.
-
- SurfaceMesh mesh;
-
- // allocate property storing a point per edge
- auto edgePoints = mesh.addEdgeProperty("propertyName");
-
- // access the edge property like an array
- SurfaceMesh::Edge e;
- edgePoints[e] = Point(x,y,z);
-
- // remove property and free memory
- mesh.removeEdgeProperty(edgePoints);
-
-
-# Connectivity Queries {#connectivity}
-
-Commonly used connectivity queries such as retrieving the next
-halfedge or the target vertex of an halfedge are illustrated below.
-
- SurfaceMesh::Halfedge h;
- auto h0 = mesh.nextHalfedge(h);
- auto h1 = mesh.prevHalfedge(h);
- auto h2 = mesh.oppositeHalfedge(h);
- auto f = mesh.face(h);
- auto v0 = mesh.fromVertex(h);
- auto v1 = mesh.toVertex(h);
-
-
-
-# Topological Operations {#topology}
-
-SurfaceMesh also offers higher-level topological operations, such as performing
-edge flips, edge splits, face splits, or halfedge collapses. The figure below
-illustrates some of these operations.
-
-
-
-The corresponding member functions and their syntax is demonstrated in the
-pseudo-code below.
-
- SurfaceMesh::Vertex v;
- SurfaceMesh::Edge e;
- SurfaceMesh::Halfedge h;
- SurfaceMesh::Face f;
-
- mesh.split(f, v);
- mesh.split(e, v);
- mesh.flip(e);
- mesh.collapse(h);
-
-When entities are removed from the mesh due to topological changes, the member
-function `garbageCollection()` has to be called in order to ensure the
-consistency of the data structure.
+This section provides a high-level overview of the pmp-library. We describe its
+design as well as the capabilities provided by the library. The pmp-library is
+organized into different modules. At the core of the library is the @ref
+geometry module providing data structures for point sets, edge sets, and
+polygonal surface meshes. On top of the @ref geometry module the @ref algorithms
+module provides implementations of canonical geometry processing algorithms such
+as remeshing, simplification, subdivision, and smoothing. The @ref io module
+provides classes for reading and writing data structures of the @ref geometry
+module to common file formats. The optional @ref gl module provides
+OpenGL®-based viewers and visualization tools.
+
+## The `geometry` Module
+
+The core of the library is the geometry module providing a set of data
+structures for common geometry processing tasks. At this point, pmp-library
+provides data structures pmp::PointSet, pmp::EdgeSet, and
+pmp::SurfaceMesh. These classes form a simple inheritance hierarchy. The
+pmp::GeometryObject base class contains functionality common to all types of
+geometry representations, such as having certain spatial bounds and giving
+access to the underlying points. Furthermore, it also defines the base class for
+entity handles and functions for handling global object properties.
+
+## The `algorithms` Module
+
+The @ref algorithms module provides implementations of canonical geometry
+processing algorithms such as remeshing or mesh simplification. The class
+structure and naming follows a simple and straightforward scheme: Provide one
+class for one type of tasks, and name it according to the data structure it is
+operating on. Example: the pmp::SurfaceRemeshing class provides remeshing
+algorithms operating on surface meshes. Similarly, the pmp::PointSetSmoothing
+class can be used to smooth point sets.
+
+## The `io` Module
+
+This module provides readers and writers for common file formats. For each data
+structure of the @ref geometry module a corresponding IO class is provided,
+e.g., pmp::SurfaceMeshIO and pmp::PointSetIO. For convenience, the IO
+functionality is easily accessible using the `read()` and `write()` member
+functions. The only required argument is a file name. The corresponding file
+format is automatically determined by the file extension. Additional
+pmp::IOOptions can be used to control _what_ data is written, e.g., including
+vertex normals or not, and _how_ it is written, i.e., as plain text ASCII or
+binary files.
+
+## The `gl` Module
+
+In order to easily create visualizations the library contains an optional @ref
+gl module including basic viewers for all @ref geometry structures, i.e., a
+pmp::PointSetViewer, pmp::EdgeSetViewer, and a pmp::MeshViewer. Similar to the
+@ref io module, the corresponding OpenGL® code for rendering the data is
+implemented using one class for each data type, e.g., pmp::EdgeSetGL. For
+simplicity, the @ref gl classes inherit from their corresponding @ref geometry
+classes in order to access internal data structures.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index cf5d232..26e95e7 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,4 +1,35 @@
# Quickstart {#quickstart}
-Write me: How to setup a simple cmake-based project using pmp, creating a
-custom mesh viewer to implement some algorithm. Provide ready-to use template.
+This section briefly describes how to get up and running using the
+pmp-library. See [Installation](installation.html) for more detailed
+information such as system requirements and different ways of installing and
+using pmp-library.
+
+## Building the Library
+
+Fetch the repository:
+
+ $ git clone --recursive https://github.com/pmp-library/pmp-library.git
+
+Configure and build:
+
+ $ cd pmp-library && mkdir build && cd build && cmake .. && make
+
+Load and view a mesh:
+
+ $ ./mview ../external/pmp-data/off/bunny.off
+
+## Using the Project Template
+
+We also provide a simple project template for writing your own algorithms and
+applications using the pmp-library. It directly includes the pmp-library
+repository as a git submodule. To get started, just clone the repository
+recursively:
+
+ $ git clone --recursive https://github.com/pmp-library/pmp-template.git
+
+Configure and build:
+
+ $ cd pmp-template && mkdir build && cd build && cmake .. && make
+
+This will automatically build the pmp-library and its dependecies.
diff --git a/docs/style.css b/docs/style.css
index 7a44c6c..39a6d8f 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -28,8 +28,59 @@ body, table, div, p, dl
#footer address
{
+ border-top: 2px solid #09a8ff;
padding-top: 10px;
padding-bottom: 10px;
font-size: normal;
text-align: center;
-}
\ No newline at end of file
+}
+
+div.header
+{
+ background-image:none;
+ background-repeat:repeat-x;
+ background-color: #ffffff;
+ margin: 0px;
+ margin-left: 12px;
+ border-bottom: none;
+}
+
+#nav-tree
+{
+ background-image:none;
+ background-repeat:repeat-x;
+ background-color: #ffffff;
+ -webkit-overflow-scrolling : touch; /* iOS 5+ */
+}
+
+div.contents {
+ margin-top: 10px;
+ margin-left: 24px;
+ margin-right: 8px;
+ width: 60em;
+}
+
+.ui-resizable-e {
+ background:url("splitbar.png") repeat scroll right center transparent;
+ background: #09a8ff;
+ cursor:e-resize;
+ height:100%;
+ right:0;
+ top:0;
+ width:2px;
+}
+
+#titlearea
+{
+ padding: 0px;
+ margin: 0px;
+ width: 100%;
+ border-bottom: 2px solid #09a8ff;
+}
+
+.title {
+ font: 400 14px/28px Lato, Open Sans, sans-serif;
+ font-size: 200%;
+ font-weight: bold;
+ margin: 10px 2px 0px 2px;
+}
diff --git a/docs/tutorial.md b/docs/tutorial.md
new file mode 100644
index 0000000..e152335
--- /dev/null
+++ b/docs/tutorial.md
@@ -0,0 +1,220 @@
+# Turorial {#tutorial}
+
+This section provides a hands-on tutorial on the basic usage of the
+pmp-library. Since working with polygon meshes is the focus of the library, this
+tutorial uses the pmp::SurfaceMesh class throughout the examples. However, the
+general concepts such as iterating through the entities of a data set naturally
+transfer to other representations as well.
+
+## Introduction
+
+In general, a polygonal surface mesh is composed of vertices, edges and faces as
+well as the incidence relationships between them. pmp::SurfaceMesh stores the
+connectivity information based on halfedges, i.e., pairs of directed edges with
+opposing direction. To be more precise:
+
+- Each vertex stores an outgoing halfedge.
+- Each face stores an incident halfedge.
+- Each halfedge stores its incident face, its target vertex, and its previous
+ and next halfedges within the face.
+
+The halfedge connectivity is illustrated in the figure below:
+
+
+
+In the following sections we describe the basic usage of pmp::SurfaceMesh by
+means of simple example programs and code excerpts.
+
+## Basics
+
+The very basic usage of pmp::SurfaceMesh is demonstrated in the example below. The
+program first instantiates a pmp::SurfaceMesh object as well as four vertex
+handles. These handles, as well as the handles for the other mesh entities
+`Halfedge`, `Edge` and `Face` basically indices. Four vertices are added to the
+mesh, as well as four triangular faces composing a tetrahedron. Finally, the
+number of vertices, edges, and faces is printed to standard output.
+
+~~~~{.cpp}
+ // instantiate a SurfaceMesh object
+ SurfaceMesh mesh;
+
+ // instantiate 4 vertex handles
+ SurfaceMesh::Vertex v0,v1,v2,v3;
+
+ // add 4 vertices
+ v0 = mesh.addVertex(Point(0,0,0));
+ v1 = mesh.addVertex(Point(1,0,0));
+ v2 = mesh.addVertex(Point(0,1,0));
+ v3 = mesh.addVertex(Point(0,0,1));
+
+ // add 4 triangular faces
+ mesh.addTriangle(v0,v1,v3);
+ mesh.addTriangle(v1,v2,v3);
+ mesh.addTriangle(v2,v0,v3);
+ mesh.addTriangle(v0,v2,v1);
+
+ std::cout << "vertices: " << mesh.nVertices() << std::endl;
+ std::cout << "edges: " << mesh.nEdges() << std::endl;
+ std::cout << "faces: " << mesh.nFaces() << std::endl;
+~~~~
+
+## Iterators and Circulators
+
+In order to sequentially access mesh entities pmp::SurfaceMesh provides
+iterators for each entity type, namely pmp::PointSet::VertexIterator,
+pmp::EdgeSet::HalfedgeIterator, pmp::EdgeSet::EdgeIterator, and
+pmp::SurfaceMesh::FaceIterator. Similar to iterators, pmp::SurfaceMesh also
+provides circulators for the ordered enumeration of all incident vertices,
+halfedges, or faces around a given face or vertex. The example below
+demonstrates the use of iterators and circulators for computing the mean valence
+of a mesh.
+
+~~~~{.cpp}
+ SurfaceMesh mesh;
+
+ if (argc > 1)
+ mesh.read(argv[1]);
+
+ float meanValence = 0.0f;
+
+ // loop over all vertices
+ for (auto v : mesh.vertices())
+ {
+ // sum up vertex valences
+ meanValence += mesh.valence(v);
+ }
+
+ meanValence /= mesh.nVertices();
+
+ std::cout << "mean valence: " << meanValence << std::endl;
+~~~~
+
+## Dynamic Properties
+
+Attaching additional attributes to mesh entities is important for many
+applications. pmp::SurfaceMesh supports properties by means of synchronized arrays
+that can be (de-)allocated dynamically at run-time. Property arrays are also
+used internally, e.g., to store vertex coordinates. The example program below
+shows how to access vertex coordinates through the (pre-defined) point property.
+
+~~~~{.cpp}
+ SurfaceMesh mesh;
+
+ if (argc > 1)
+ mesh.read(argv[1]);
+
+ // get (pre-defined) property storing vertex positions
+ auto points = mesh.getVertexProperty("v:point");
+
+ Point p(0,0,0);
+
+ for (auto v : mesh.vertices())
+ {
+ // access point property like an array
+ p += points[v];
+ }
+
+ p /= mesh.nVertices();
+
+ std::cout << "barycenter: " << p << std::endl;
+~~~~
+
+The dynamic (de-)allocation of properties at run-time is managed by a set
+of four different functions:
+
+- `addEntityTypeProperty("PropertyName")` allocates a new property
+ for the given _EntityType_ of the type _PropertyType_ labeled by the
+ _PropertyName_ string.
+- `getEntityTypeProperty("PropertyName")` returns a handle to an
+ existing property.
+- `EntityTypeProperty("PropertyName")` returns a handle to an
+ existing property if the specified property already exists. If not, a new
+ property is allocated and its handle is returned.
+- `removeEntityTypeProperty(PropertyHandle)` removes and the property referenced
+ by `PropertyHandle`.
+
+Functions that allocate a new property take a default value for the property as
+an optional second argument. The code excerpt below demonstrates how to
+allocate, use and remove a custom edge property.
+
+~~~~{.cpp}
+ SurfaceMesh mesh;
+
+ // allocate property storing a point per edge
+ auto edgePoints = mesh.addEdgeProperty("propertyName");
+
+ // access the edge property like an array
+ SurfaceMesh::Edge e;
+ edgePoints[e] = Point(x,y,z);
+
+ // remove property and free memory
+ mesh.removeEdgeProperty(edgePoints);
+~~~~
+
+## Connectivity Queries
+
+Commonly used connectivity queries such as retrieving the next
+halfedge or the target vertex of an halfedge are illustrated below.
+
+~~~~{.cpp}
+ SurfaceMesh::Halfedge h;
+ auto h0 = mesh.nextHalfedge(h);
+ auto h1 = mesh.prevHalfedge(h);
+ auto h2 = mesh.oppositeHalfedge(h);
+ auto f = mesh.face(h);
+ auto v0 = mesh.fromVertex(h);
+ auto v1 = mesh.toVertex(h);
+~~~~
+
+
+
+## Topological Operations
+
+pmp::SurfaceMesh also offers higher-level topological operations, such as
+performing edge flips, edge splits, face splits, or halfedge collapses. The
+figure below illustrates some of these operations.
+
+
+
+The corresponding member functions and their syntax is demonstrated in the
+pseudo-code below.
+
+~~~~{.cpp}
+ SurfaceMesh::Vertex v;
+ SurfaceMesh::Edge e;
+ SurfaceMesh::Halfedge h;
+ SurfaceMesh::Face f;
+
+ mesh.split(f, v);
+ mesh.split(e, v);
+ mesh.flip(e);
+ mesh.collapse(h);
+~~~~
+
+When entities are removed from the mesh due to topological changes, the member
+function pmp::GeometryObject::garbageCollection() has to be called in order to
+ensure the consistency of the data structure.
+
+## File I/O
+
+pmp::SurfaceMesh currently supports reading OFF, OBJ, and STL files. Write
+support is currently limited to OFF files. All I/O operations are handled by the
+pmp::SurfaceMesh::read() and pmp::SurfaceMesh::write() member functions, with
+the target file name being their only argument. An example is given below.
+
+~~~~{.cpp}
+ // instantiate a SurfaceMesh object
+ SurfaceMesh mesh;
+
+ // read a mesh specified as the first command line argument
+ if (argc > 1)
+ mesh.read(argv[1]);
+
+ // ...
+ // do fancy stuff with the mesh
+ // ...
+
+ // write the mesh to the file specified as second argument
+ if (argc > 2)
+ mesh.write(argv[2]);
+~~~~
diff --git a/docs/userguide.md b/docs/userguide.md
new file mode 100644
index 0000000..e50d2af
--- /dev/null
+++ b/docs/userguide.md
@@ -0,0 +1,10 @@
+# User Guide {#guide}
+
+This User Guide is organized into the following sections
+
+- @subpage quickstart -- how to quickly using the pmp-library
+- @subpage installation -- detailed installation instructions
+- @subpage overview -- an overview of the library and its capabilities
+- @subpage tutorial -- how to perform basic tasks
+- @subpage contributing -- guidelines for contributions
+- @subpage codingstyle -- contains our coding guidelines
+
+
+
+
+
+
diff --git a/docs/images/pmp-logo-text-smaller.png b/docs/images/pmp-logo-text-smaller.png
new file mode 100644
index 0000000..7443ad8
Binary files /dev/null and b/docs/images/pmp-logo-text-smaller.png differ
diff --git a/docs/installation.md b/docs/installation.md
index 22f4399..d2adec3 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,28 +1,48 @@
# Installation {#installation}
-# System Requirements {#system_requirements}
+In this section, we describe how to configure, build, and install the
+pmp-library in detail.
-pmp uses [CMake](http://www.cmake.org) as its build configuration
-system. Version 3.1 or greater is required.
+## System Requirements
-pmp requires a C++11-compliant compiler. For the current release pmp has
-been tested to build with the following compilers:
+The pmp-library uses [CMake](http://www.cmake.org) as its build configuration
+system. Version 3.0.2 or greater is required. The pmp-library requires a
+C++11-compliant compiler. We continuously build and test the pmp-library
+with the following compilers and operating systems:
Operating System | Compiler
-----------------|--------------------
-Linux | gcc version 4.8.4
-Mac OS-X | LLVM version 5.0
-Windows | Visual Studio 2012
+Linux | gcc 4.8.4, clang 3.9.0
+Mac OS-X | AppleClang 8.1.0
+Windows | Visual Studio 2015, 2017
-# Configuration {#configuration}
+## Dependencies
-pmp relies on [CMake](http://www.cmake.org) as its build and configuration
-system. `CMake` is a cross-platform build-system capable of generating different
-build files (so-called _generators_) for a specific platform, e.g., Makefiles
-for Linux/Unix, Xcode projects for Mac OS-X and Visual Studio projects for
-Windows.
+Some parts of the pmp-library depends on the following third-party libraries:
-On the command line change to the top-level pmp directory, create a
+Library | Description | Version
+------------------------------------------|-----------------------------------|--------------
+[Eigen](http://eigen.tuxfamily.org) | C++ linear algebra library | ≥ 3.3.4
+[OpenGL](http://opengl.org) | Open Graphics Library | ≥ 3.3
+[GLEW](http://glew.sourceforge.net) | OpenGL Extension Wrangler Library | ≥ 3.3
+[GLFW](http://glfw.org) | Graphics Library Framework | ≥ 3.2.1
+[ImGui](https://github.com/ocornut/imgui) | Immediate Mode GUI | ≥ 1.51
+[Google Test](https://github.com/google/googletest) | C++ Test Framework | ≥ 1.8.0
+
+By default, we include the corresponding libraries using git submodules. Note
+that OpenGL and related dependencies are optional. They are only needed if you
+want to use the viewer classes. Google Test is optional as well and only
+required if you want to run the unit test suite.
+
+## Configuration
+
+The pmp-library relies on [CMake](http://www.cmake.org) as its build and
+configuration system. `CMake` is a cross-platform build-system capable of
+generating different build files (so-called _generators_) for a specific
+platform, e.g., Makefiles for Linux/Unix, Xcode projects for Mac OS-X and Visual
+Studio projects for Windows.
+
+On the command line change to the top-level pmp-library directory, create a
build directory and run `cmake`:
$ cd pmp
@@ -55,33 +75,31 @@ customizing its configuration see
the [CMake documentation](http://cmake.org/cmake/help/documentation.html).
-# Building pmp {#building}
+## Building
-After successful configuration pmp can be build using
-the chosen build system. For a Unix-like environment the default
-generator is Makefiles. In order to build pmp just call
+After successful configuration pmp-library can be build using the chosen build
+system. For a Unix-like environment the default generator is Makefiles. In order
+to build pmp-library just call
$ make
-from the top-level build directory. In order to build
-pmp in parallel use the `-j` option of
-`make`:
+from the top-level build directory. In order to build pmp in parallel use the
+`-j` option of `make`:
$ make -j
-The resulting library is named |
+ $projectname
+ $projectnumber
+
+ $projectbrief
+ |
+
+
+
+
+ $projectbrief
+ |
+
+
+
+
+ $searchbox | + + +
pmp.so and
+The resulting library is named libpmp.so and
located in the current working directory.
-In order to build the full HTML manual and reference
-documentation call
+In order to build the full HTML manual and reference documentation call
$ make docs
-The resulting HTML documentation can be found in the `doc/` sub-directory.
+The resulting HTML documentation can be found in the `docs/` sub-directory.
-# Installation {#make_installation}
+## Installation
-In order to install pmp just call
+In order to install pmp-library just call
$ sudo make install
@@ -92,10 +110,10 @@ prefix during build configuration:
$ cmake -DCMAKE_INSTALL_PREFIX=