Improve docs

- integrate tutorial into guide
- add dedicated pages for algorithms usage
- add missing reference docs

Signed-off-by: Daniel Sieger <dsieger@posteo.de>

README.md

@@ -45,9 +45,13 @@ int main(void)
 }
 ```
 
+## Read the Docs
+
+The [user guide](https://www.pmp-library.org/guide.html) contains all you need to get started using PMP, including a [tutorial](https://www.pmp-library.org/tutorial.html) covering mesh processing basics.
+
 ## Contribute
 
-Contributions to PMP are welcome. See the [contributing](https://www.pmp-library.org/contributing.html) section of the [user guide](https://www.pmp-library.org/guide.html).
+Contributions to PMP are welcome! There are many ways you can help: Report any [issues](https://github.com/pmp-library/pmp-library/issues) you find, help to improve the documentation, join our [discussions](https://github.com/pmp-library/pmp-library/discussions) forum, or [contribute](https://www.pmp-library.org/contributing.html) new code.
 
 ## Acknowledge
 

docs/advanced.md

@@ -0,0 +1,3 @@
+# Advanced {#advanced}
+
+- @subpage eigen -- interfacing with Eigen

docs/algorithms.md

@@ -0,0 +1,11 @@
+# Algorithms {#algorithms-guide}
+
+PMP comes with several standard mesh processing algorithms and utility functions. The following list is not exhaustive:
+
+- @subpage decimation -- reduce the number of elements in a mesh
+- @subpage remeshing -- improve the shape and size of mesh elements
+- @subpage subdivision -- refine a mesh by subdividing elements
+- @subpage smoothing -- reduce noise and surface roughness
+- @subpage hole_filling -- close holes in the mesh
+
+See the \ref algorithms module API reference documentation for the full details.

docs/decimation.md

@@ -0,0 +1,26 @@
+# Decimation {#decimation}
+
+Mesh decimation reduces the number of elements in a mesh while preserving additional attributes such as surface approximation error or triangle quality. Our implementation performs incremental greedy mesh decimation based on halfedge collapses.
+
+The function is pmp::decimate().
+
+See \cite kobbelt_1998_general and \cite garland_1997_surface for more details.
+
+\note This algorithm only works on triangle meshes.
+
+## Parameters
+
+The decimation function can be controlled by the following parameters:
+
+- `n_vertices`: Control the target number of vertices
+- `aspect_ratio`: Threshold for the quality of the triangles in the mesh.
+- `edge_length`: Specify a minimum target edge length.
+- `max_valence`: Control the maximum number of incident edges per vertex.
+- `normal_deviation`: Control the maximum deviation of normals.
+- `hausdorff_error`: The maximum deviation from the original surface.
+- `seam_threshold`: Threshold for detecting texture seams.
+- `seam_angle_deviation`: The maximum texture seam deviation.
+
+## Selections
+
+The decimation algorithm supports selections. You can select a subset of all vertices in the mesh to perform the simplification. This is done using the boolean `v:selected` vertex property.

docs/developers.md

@@ -0,0 +1,4 @@
+# Developers {#developers}
+
+- @subpage contributing -- instructions for submitting contributions
+- @subpage codingstyle -- the coding style we follow around here

docs/guide.md

@@ -1,13 +1,28 @@
 # Guide {#guide}
 
-Welcome to the PMP library guide! This guide contains detailed information about PMP and contains the following sections:
+Welcome to the PMP library guide! This guide provides detailed information about PMP.
+
+The basics section contains the following pages:
 
 - @subpage installation -- detailed installation instructions
 - @subpage overview -- an overview of the library and its capabilities
-- @subpage contributing -- guidelines for contributions
-- @subpage codingstyle -- contains our coding guidelines
-- @subpage eigen -- interfacing with Eigen
+- @subpage tutorial -- learn the basics of working with PMP
+
+The @subpage algorithms-guide section contains task-specific guides:
+
+- @ref decimation -- reduce the number of triangles in a mesh
+- @ref remeshing -- improve the shape and size of triangles
+- @ref subdivision -- refine a mesh by subdividing elements
+- @ref smoothing -- reduce noise and surface roughness
+- @ref hole_filling -- close holes in the mesh
+
+The @subpage advanced section covers special topics:
+
+- @ref eigen -- interfacing with Eigen
+
+The @subpage developers section contains guidelines for developers and contributors:
 
-See the [Tutorial](@ref tutorial) for getting started with PMP.
+- @ref contributing -- instructions for submitting contributions
+- @ref codingstyle -- coding guidelines we follow around here
 
 See the [API Reference](modules.html) for detailed information on the classes and functions provided by PMP.

docs/hole_filling.md

@@ -0,0 +1,7 @@
+# Hole filling {#hole_filling}
+
+Meshes sometimes contain holes as artifacts from previous modeling or reconstruction steps. PMP provides an algorithm for filling such holes. This algorithm fills holes in the mesh by creating an initial triangulation of the hole and applying subsequent refinement and smoothing steps to the newly created triangles.
+
+The function is pmp::fill_hole().
+
+See \cite liepa_2003_filling for details.

docs/remeshing.md

@@ -0,0 +1,51 @@
+# Remeshing {#remeshing}
+
+A common task in mesh processing is to improve the shape and size of the elements in a triangle mesh. Surface triangulations coming out of CAD programs, 3D modeling tools, or surface reconstruction can contain low quality elements not suitable for downstream processing. Low quality triangles typically include very long and skinny triangles or zero area faces.
+
+PMP provides an implementation of the remeshing algorithm by Botsch and Kobbelt \cite botsch_2004_remeshing that improves the quality of the triangles in your mesh. The algorithm is based on applying a series of local mesh modifications through edge splits, collapses, flips, as well as tangential smoothing. In addition to the standard uniform remeshing, PMP also provides a curvature-adaptive remeshing based on the paper of Dunyach et al. \cite dunyach_2013_adaptive
+
+In this section, you will learn the basics of the algorithm and how to use it effectively for remeshing tasks.
+
+\note Remeshing only works on triangle meshes.
+
+## Algorithm Basics
+
+- Incremental algorithm based on iterative refinement
+- Split, flip, collapse, smooth
+- Projection on original surface
+- Uniform vs. curvature-adaptive sizing
+
+## Uniform Remeshing
+
+Uniform remeshing creates a uniform (isotropic) triangulation with a given uniform target edge length for the whole mesh. The remeshing processing is controlled by three parameters:
+
+- `edge_length`: The target length each edge in the mesh should have after successful operation.
+- `iterations`: The number of iterations to perform.
+- `use_projection`: Enable projection of vertices back to the original input surface.
+
+A good default value for `edge_length` is the mean edge length which can be computed by the pmp::mean_edge_length() function.
+
+## Adaptive Remeshing
+
+Adaptive remeshing creates an adaptive mesh with varying element size depending on the local curvature of the input mesh. In addition
+
+- `min_edge_length`: The minimum edge length.
+- `max_edge_length`: The maximum edge length.
+- `approx_error`: The maximum approximation error.
+- `iterations`: The number of iterations.
+- `use_projection`: Enable projection of vertices back to the original input surface.
+
+## Preserving Sharp Features
+
+Both the uniform and adaptive remeshing functions preserve feature edges present in the input mesh. They can be either detected by using the pmp::detect_features() function or by using the `v:feature` boolean vertex property and the `e:feature` boolean edge property.
+
+## Selections
+
+The remeshing can be applied restricted to a subset of the mesh. Use the `v:selected` boolean property to choose the vertices to which the remeshing will be applied.
+
+## Troubleshooting
+
+- Our implementation is not perfect. If you spot a problem, please file an [issue](https://github.com/pmp-library/pmp-library/issues).
+- Degenerate faces in the input and sharp feature detection can lead to unexpected results.
+- We've had cases when the projection to the original surface causes trouble. Try disabling this step of the algorithm.
+- If you run into trouble: try with a single iteration; disable individual stages of the algorithm to nail down where things go wrong.

docs/smoothing.md

@@ -0,0 +1,8 @@
+# Smoothing {#smoothing}
+
+Mesh smoothing effectively reduces noise in the input surface. Especially meshes coming from 3D scanning and reconstruction typically contain noise.
+
+PMP provides two different methods for smoothing:
+
+1. Explicit Laplacian smoothing. See pmp::explicit_smoothing().
+2. Implicit Laplacian smoothing. See pmp::implicit_smoothing().

docs/subdivision.md

@@ -0,0 +1,7 @@
+# Subdivision {#subdivision}
+
+Subdivision can be used to refine a mesh and to compute a subdivision surface. PMP provides three different algorithms:
+
+1. Loop subdivision for triangle meshes. See pmp::loop_subdivision().
+2. Catmull-Clark subdivision for quad meshes. See pmp::catmull_clark_subdivision().
+3. Quad-tri subdivision for a mixed triangle/quad scheme. See pmp::quad_tri_subdivision().

src/pmp/algorithms/decimation.h

@@ -10,8 +10,16 @@ namespace pmp {
 //! \brief Mesh decimation based on approximation error and fairness
 //! criteria.
 //! \details Performs incremental greedy mesh decimation based on halfedge
-//! collapses.
-//! See \cite kobbelt_1998_general and \cite garland_1997_surface for details.
+//! collapses. See \cite kobbelt_1998_general and \cite garland_1997_surface for details.
+//! \param mesh Target mesh. Modified in place.
+//! \param n_vertices Target number of vertices.
+//! \param aspect_ratio Minimum aspect ratio of the triangles.
+//! \param edge_length Minimum target edge length.
+//! \param max_valence Maximum number of incident edges per vertex.
+//! \param normal_deviation Maximum deviation of face normals.
+//! \param hausdorff_error Maximum deviation from the original surface.
+//! \param seam_threshold Threshold for texture seams.
+//! \param seam_angle_deviation Maximum texture seam deviation.
 //! \pre Input mesh needs to be a triangle mesh.
 //! \throw InvalidInputException if the input precondition is violated.
 //! \ingroup algorithms

src/pmp/algorithms/subdivision.h

@@ -20,7 +20,7 @@ void catmull_clark_subdivision(SurfaceMesh& mesh);
 void loop_subdivision(SurfaceMesh& mesh);
 
 //! \brief Perform one step of quad-tri subdivision.
-//! \details See \cite stam_2003_subdiv for details.
+//! \details Suitable for mixed quad/triangle meshes. See \cite stam_2003_subdiv for details.
 //! \ingroup algorithms
 void quad_tri_subdivision(SurfaceMesh& mesh);