Merge branch 'decimater-documentation' into 'master'

document that DecimaterT::decimate does not perform garbage collection on the mesh

addressing #27 

See merge request !76

Doc/Examples/decimater.cc

@@ -1,37 +1,25 @@
-// 
+using namespace OpenMesh;
-using namespace OpenMesh
 
-// ---------------------------------------- necessary types
+typedef TriMesh_ArrayKernelT<>               Mesh;
-
+typedef Decimater::DecimaterT<Mesh>          Decimater;
-// Mesh type
+typedef Decimater::ModQuadricT<Mesh>::Handle HModQuadric;
-typedef TriMesh_ArrayKernelT<>                      Mesh;
-
-// Decimater type
-typedef Decimater::DecimaterT< Mesh >               Decimater;
-
-// Decimation Module Handle type
-typedef Decimater::ModQuadricT< Mesh >::Handle HModQuadric;
-
-// ---------------------------------------- decimater setup
 
 Mesh        mesh;             // a mesh object
 Decimater   decimater(mesh);  // a decimater object, connected to a mesh
 HModQuadric hModQuadric;      // use a quadric module
 
-decimater.add( hModQuadric ); // register module at the decimater
+decimater.add(hModQuadric); // register module at the decimater
-
+std::cout << decimater.module(hModQuadric).name() << std::endl; // module access
-std::cout << decimater.module( hModQuadric ).name() << std::endl;
-                              // the way to access the module 
 
 /*
  * since we need exactly one priority module (non-binary)
  * we have to call set_binary(false) for our priority module
  * in the case of HModQuadric, unset_max_err() calls set_binary(false) internally
  */
-decimater.module( hModQuadric ).unset_max_err();
+decimater.module(hModQuadric).unset_max_err();
 
-decimater.initialize();       // let the decimater initialize the mesh and the
+decimater.initialize();
-                              // modules
+decimater.decimate();
-
-decimater.decimate();         // do decimation
 
+// after decimation: remove decimated elements from the mesh
+mesh.garbage_collection();

Doc/decimater.docu

@@ -39,7 +39,7 @@
 
     // If halfedge is boundary, lock the corresponding vertices
     for (he_it = mesh_->halfedges_begin(); he_it != he_end ; ++he_it)
-      if (mesh_->is_boundary(*he_it) ) {
+      if (mesh_->is_boundary(*he_it)) {
          mesh_->status(_mesh->to_vertex_handle(*he_it)).set_locked(true);
          mesh_->status(_mesh->from_vertex_handle(*he_it)).set_locked(true);
       }

src/OpenMesh/Tools/Decimater/DecimaterT.hh

@@ -101,21 +101,43 @@ public: //------------------------------------------------------ public methods
 
 public:
 
-  /** Decimate (perform _n_collapses collapses). Return number of
+  /**
-      performed collapses. If _n_collapses is not given reduce as
+   * @brief Perform a number of collapses on the mesh.
-      much as possible */
+   * @param _n_collapses Desired number of collapses. If zero (default), attempt
+   *                     to do as many collapses as possible.
+   * @return Number of collapses that were actually performed.
+   * @note This operation only marks the removed mesh elements for deletion. In
+   *       order to actually remove the decimated elements from the mesh, a
+   *       subsequent call to ArrayKernel::garbage_collection() is required.
+   */
   size_t decimate( size_t _n_collapses = 0 );
 
-  /// Decimate to target complexity, returns number of collapses
+  /**
+   * @brief Decimate the mesh to a desired target vertex complexity.
+   * @param _n_vertices Target complexity, i.e. desired number of remaining
+   *                    vertices after decimation.
+   * @return Number of collapses that were actually performed.
+   * @note This operation only marks the removed mesh elements for deletion. In
+   *       order to actually remove the decimated elements from the mesh, a
+   *       subsequent call to ArrayKernel::garbage_collection() is required.
+   */
   size_t decimate_to( size_t  _n_vertices )
   {
     return ( (_n_vertices < this->mesh().n_vertices()) ?
 	     decimate( this->mesh().n_vertices() - _n_vertices ) : 0 );
   }
 
-  /** Decimate to target complexity (vertices and faces).
+  /**
-   *  Stops when the number of vertices or the number of faces is reached.
+   * @brief Attempts to decimate the mesh until a desired vertex or face
-   *  Returns number of performed collapses.
+   *        complexity is achieved.
+   * @param _n_vertices Target vertex complexity.
+   * @param _n_faces Target face complexity.
+   * @return Number of collapses that were actually performed.
+   * @note Decimation stops as soon as either one of the two complexity bounds
+   *       is satisfied.
+   * @note This operation only marks the removed mesh elements for deletion. In
+   *       order to actually remove the decimated elements from the mesh, a
+   *       subsequent call to ArrayKernel::garbage_collection() is required.
    */
   size_t decimate_to_faces( size_t  _n_vertices=0, size_t _n_faces=0 );