Heavily commented, restructured and debugged the basic hole filling code

vcg/complex/algorithms/hole.h

@@ -36,6 +36,7 @@
 namespace vcg {
     namespace tri {
 
+    
     /*
     An ear is identified by TWO pos.
     The Three vertexes of an Ear are:
@@ -46,22 +47,22 @@ namespace vcg {
       e1 == e0.NextB();
       e1.FlipV() == e0;
 
-    Situazioni ear non manifold, e degeneri (buco triangolare)
+    */
-
+/**
-    T  XXXXXXXXXXXXX    A        /XXXXX        B      en/XXXXX
+ * Basic class for representing an 'ear' in a hole. 
-    /XXXXXXXXXXXXXXX            /XXXXXX                /XXXXXX
+ * 
-    XXXXXXep==en XXX     ep\   /en XXXX               /e1 XXXX
+ * Require FF-adajcncy and edge-manifoldness around the mesh (at most two triangles per edge)
-    XXXXXX ----/| XX   ------ ----/| XX       ------ ----/|XXX
+ * 
-    XXXXXX|   /e1 XX   XXXXXX|   /e1 XX       XXXXXX|  o/e0 XX
+ * An ear is represented by two consecutive Pos e0,e1.
-    XXXXXX|  /XXXXXX   XXXXXX|  /XXXXXX       XXXXXX|  /XXXXXX
+ * The vertex pointed by the first pos is the 'corner' of the ear
-    XXX e0|o/XXXXXXX   XXX e0|o/XXXXXXX       XXX ep| /XXXXXXX
+ * 
-    XXX  \|/XXXXXXXX   XXX  \|/XXXXXXXX       XXX  \|/XXXXXXXX
+ *
-    XXXXXXXXXXXXXXXX   XXXXXXXXXXXXXXXX       XXXXXXXXXXXXXXXX
  */
 template<class MESH> class TrivialEar
 {
 public:
   typedef typename MESH::FaceType      FaceType;
+  typedef typename MESH::VertexType    VertexType;
   typedef typename MESH::FacePointer   FacePointer;
   typedef typename MESH::VertexPointer VertexPointer;
   typedef typename face::Pos<FaceType> PosType;
@@ -71,6 +72,7 @@ public:
   PosType e0;
   PosType e1;
   CoordType n; // the normal of the face defined by the ear
+  
   const char * Dump() {return 0;}
   // The following members are useful to consider the Ear as a generic <triangle>
   // with p0 the 'center' of the ear.
@@ -116,14 +118,50 @@ public:
   virtual	void ComputeQuality() {	quality = QualityFace(*this) ; }
   bool IsUpToDate()	{return ( e0.IsBorder() && e1.IsBorder());}
   // An ear is degenerated if both of its two endpoints are non manifold.
-  bool IsDegen(const int nonManifoldBit)
+  bool IsDegen()
   {
-    if(e0.VFlip()->IsUserBit(nonManifoldBit) && e1.V()->IsUserBit(nonManifoldBit))
+    if(e0.VFlip()->IsUserBit(NonManifoldBit()) && e1.V()->IsUserBit(NonManifoldBit()))
       return true;
     else return false;
   }
   bool IsConcave() const {return(angleRad > (float)M_PI);}
 
+  
+  /** NonManifoldBit
+   * To handle non manifoldness situations we keep track 
+   * of the vertices of the hole boundary that are traversed by more than a single boundary.
+   * 
+   */
+  static int &NonManifoldBit() { static int _NonManifoldBit=0; return _NonManifoldBit; }
+  static int InitNonManifoldBitOnHoleBoundary(const PosType &p)       
+  {
+    if(NonManifoldBit()==0) 
+      NonManifoldBit() = VertexType::NewBitFlag(); 
+    int holeSize=0;
+    
+    //First loop around the hole to mark non manifold vertices.
+    PosType ip = p;   // Pos iterator
+    do{
+      ip.V()->ClearUserBit(NonManifoldBit());
+      ip.V()->ClearV();
+      ip.NextB();
+      holeSize++;
+    } while(ip!=p);
+    
+    ip = p;   // Re init the pos iterator for another loop (useless if everithing is ok!!)
+    do{
+      if(!ip.V()->IsV())
+        ip.V()->SetV();  
+      else  // All the vertexes that are visited more than once are non manifold
+        ip.V()->SetUserBit(NonManifoldBit());
+      ip.NextB();
+    } while(ip!=p);
+    return holeSize;
+  }
+  
+  
+  
+  
   // When you close an ear you have to check that the newly added triangle does not create non manifold situations
   // This can happen if the new edge already exists in the mesh.
   // We test that looping around one extreme of the ear we do not find the other vertex
@@ -141,8 +179,38 @@ public:
     while(!pp.IsBorder());
     return true;
   }
+  /**
+   * @brief Close the current ear by adding a triangle to the mesh
+   * and returning up to two new possible ears to be closed. 
+   * 
+   * @param np0 The first new pos to be inserted in the heap
+   * @param np1 The second new pos
+   * @param f the already allocated face to be used to close the ear
+   * @return true if it successfully add a triangle 
+   * 
+   *  +\                      
+   *  +++\             ------- 
+   *  +++ep\         /| +++en/\
+   *  +++---|      /e1 ++++++++\
+   *  ++++++|    /++++++++++++++\
+   *  +++ e0|o /+++++++++++++++++++
+   *  +++  \|/+++++++++++++++++++++
+   *  +++++++++++++++++++++++++++++
+   * 
+   *    There are three main peculiar cases:
    
-  virtual bool Close(PosType &np0, PosType &np1, FaceType * f)
+   *   (T)+++++++++++++    (A)       /+++++       (B)       /en+++++++
+   *   /+++++++++++++++             /++++++                /++++++++++
+   *   ++++++ep==en +++      ep\   /en ++++               /e1 ++++++++
+   *   ++++++ ----/| ++    ------ ----/| ++       ------------/|+++
+   *   ++++++|   /e1 ++    ++++++|   /e1 ++       ++++++|   o/e0|+++
+   *   ++++++|  /++++++    ++++++|  /++++++       ++++++|  /++++++++
+   *   +++ e0|o/+++++++    +++ e0|o/+++++++       +++ ep| /++++++++++
+   *   +++  \|/++++++++    +++  \|/++++++++       +++  \|/++++++++++++
+   *   ++++++++++++++++    ++++++++++++++++       ++++++++++++++++++++
+   */
+  
+  virtual bool Close(PosType &np0, PosType &np1, FaceType *f)
   {
     // simple topological check
     if(e0.f==e1.f) {
@@ -150,9 +218,8 @@ public:
       return false;
     }
 
-    //usato per generare una delle due nuove orecchie.
+    PosType	ep=e0; ep.FlipV(); ep.NextB(); ep.FlipV(); // ep previous
-    PosType	ep=e0; ep.FlipV(); ep.NextB(); ep.FlipV(); // he precedente a e0
+    PosType	en=e1; en.NextB();												 // en next
-    PosType	en=e1; en.NextB();												 // he successivo a e1
     if(ep!=en)
       if(!CheckManifoldAfterEarClose()) return false;
 
@@ -165,7 +232,7 @@ public:
     face::FFAttachManifold(f,1,e1.f,e1.z);
     face::FFSetBorder(f,2);
 
-    // caso ear degenere per buco triangolare
+    // First Special Case (T): Triangular hole
     if(ep==en)
     {
       //printf("Closing the last triangle");
@@ -173,30 +240,38 @@ public:
       np0.SetNull();
       np1.SetNull();
     }
-    // Caso ear non manifold a
+    // Second Special Case (A): Non Manifold on ep 
     else if(ep.v==en.v)
     {
       //printf("Ear Non manif A\n");
+      assert(ep.v->IsUserBit(NonManifoldBit()));
+      ep.v->ClearUserBit(NonManifoldBit());
       PosType	enold=en;
       en.NextB();
       face::FFAttachManifold(f,2,enold.f,enold.z);
       np0=ep;
-      np1=en;
+      assert(!np0.v->IsUserBit(NonManifoldBit()));      
+      np1.SetNull();
     }
-    // Caso ear non manifold b
+    // Third Special Case (B): Non Manifold on e1
     else if(ep.VFlip()==e1.v)
     {
+      assert(e1.v->IsUserBit(NonManifoldBit()));
+      e1.v->ClearUserBit(NonManifoldBit());
       //printf("Ear Non manif B\n");
       PosType	epold=ep;
       ep.FlipV(); ep.NextB(); ep.FlipV();
       face::FFAttachManifold(f,2,epold.f,epold.z);
       np0=ep;  // assign the two new
-      np1=en;  // pos that denote the ears
+      assert(!np0.v->IsUserBit(NonManifoldBit()));            
+      np1.SetNull();  // pos that denote the ears
     }
-    else // caso standard // Now compute the new ears;
+    else // Standard Case.
     {
       np0=ep;
+      if(np0.v->IsUserBit(NonManifoldBit())) np0.SetNull();
       np1=PosType(f,2,e1.v);
+      if(np1.v->IsUserBit(NonManifoldBit())) np1.SetNull();
     }
 
     return true;
@@ -315,12 +390,12 @@ public:
   }
 }; // end class SelfIntersectionEar
 
-// Funzione principale per chiudier un buco in maniera topologicamente corretta.
-// Gestisce situazioni non manifold ragionevoli
-// (tutte eccetto quelle piu' di 2 facce per 1 edge).
-// Controlla che non si generino nuove situazioni non manifold chiudendo orecchie
-// che sottendono un edge che gia'esiste.
 
+
+/** Hole
+ * Main hole filling templated class. 
+ * 
+ */
 template <class MESH>
 class Hole
 {
@@ -386,103 +461,67 @@ public:
   };
 
                
-        class EdgeToBeAvoided
+/** FillHoleEar
-        {
+ * Main Single Hole Filling Function                         
-          VertexPointer v0,v1;
+ * Given a specific hole (identified by the Info h) it fills it 
-          EdgeToBeAvoided(VertexPointer _v0, VertexPointer _v1):v0(_v0),v1(_v1)
+ * It also update a vector of face pointers                     
-          {
+ * It uses a priority queue to choose the best ear to be closed          
-            if(v0>v1) swap(v0,v1);
+ */
-          }
-          bool operator < (const EdgeToBeAvoided &e)
-          {
-            if(this->v0!=e.v0) return this->v0<e.v0;
-            return this->v1<e.v1;
-          }
-        };
-/// Main Single Hole Filling Function
-/// Given a specific hole (identified by the Info h) it fills it
-/// It also update a vector of face pointers
-/// It uses an heap to choose the best ear to be closed
         
 template<class EAR>
     static void FillHoleEar(MESH &m, // The mesh to be filled
-                            Info &h, // the particular hole to be filled
+                            const PosType &p, // the particular hole to be filled
                             std::vector<FacePointer *> &facePointersToBeUpdated)
     {
-      //Aggiungo le facce e aggiorno il puntatore alla faccia!
-      FaceIterator f = tri::Allocator<MESH>::AddFaces(m, h.size-2, facePointersToBeUpdated);
       
-      assert(h.p.f >= &*m.face.begin());
+      assert(tri::IsValidPointer(m,p.f));
-      assert(h.p.f <= &m.face.back());
+      assert(p.IsBorder());
-      assert(h.p.IsBorder());
+      int holeSize = EAR::InitNonManifoldBitOnHoleBoundary(p);
+      FaceIterator f = tri::Allocator<MESH>::AddFaces(m, holeSize-2, facePointersToBeUpdated);
 
-      std::vector< EAR > EarHeap;
+      std::priority_queue< EAR > EarHeap;
-      EarHeap.reserve(h.size);
+      PosType fp = p;
-      int nmBit= VertexType::NewBitFlag(); // non manifoldness bit
-
-      //First loops around the hole to mark non manifold vertices.
-      PosType ip = h.p;   // Pos iterator
-      do{
-        ip.V()->ClearUserBit(nmBit);
-        ip.V()->ClearV();
-        ip.NextB();
-      } while(ip!=h.p);
-
-      ip = h.p;   // Re init the pos iterator for another loop (useless if everithing is ok!!)
-      do{
-        if(!ip.V()->IsV())
-          ip.V()->SetV();   // All the vertexes that are visited more than once are non manifold
-        else ip.V()->SetUserBit(nmBit);
-        ip.NextB();
-      } while(ip!=h.p);
-
-      PosType fp = h.p;
       do{
         EAR appEar = EAR(fp);
-        EarHeap.push_back( appEar );
+        if(!fp.v->IsUserBit(EAR::NonManifoldBit()))
+           EarHeap.push( appEar );
         //printf("Adding ear %s ",app.Dump());
         fp.NextB();
         assert(fp.IsBorder());
-      }while(fp!=h.p);
+      }while(fp!=p);
 
-      int cnt=h.size;
+      // Main Ear closing Loop
-
+      while( holeSize > 2 && !EarHeap.empty() )
-      make_heap(EarHeap.begin(), EarHeap.end());
-
-      //finche' il buco non e' chiuso o non ci sono piu' orecchie da analizzare.
-      while( cnt > 2 && !EarHeap.empty() )
       {
-        //printf("Front of the heap is %s", H.front().Dump());
+        EAR BestEar=EarHeap.top();
-        pop_heap(EarHeap.begin(), EarHeap.end());	 // retrieve the MAXIMUM value and put in the back;
+        EarHeap.pop();
-        EAR BestEar=EarHeap.back();
-        EarHeap.pop_back();
 
-        if(BestEar.IsUpToDate() && !BestEar.IsDegen(nmBit))
+        if(BestEar.IsUpToDate() && !BestEar.IsDegen())
         {
           if((*f).HasPolyInfo()) (*f).Alloc(3);
           PosType ep0,ep1;
           if(BestEar.Close(ep0,ep1,&*f))
           {
             if(!ep0.IsNull()){
-              EarHeap.push_back(EAR(ep0));
+              assert(!ep0.v->IsUserBit(EAR::NonManifoldBit()));
-              push_heap( EarHeap.begin(), EarHeap.end());
+              EarHeap.push(EAR(ep0));
             }
             if(!ep1.IsNull()){
-              EarHeap.push_back(EAR(ep1));
+              assert(!ep1.v->IsUserBit(EAR::NonManifoldBit()));
-              push_heap( EarHeap.begin(), EarHeap.end());
+              EarHeap.push(EAR(ep1));
             }
-            --cnt;
+            --holeSize;
             ++f;
           }
         }//is update()
-      }//fine del while principale.
+      } 
       
+      // If the hole had k non manifold vertexes it requires less than n-2 face ( it should be n - 2*(k+1) ), 
+      // so we delete the remaining ones. 
       while(f!=m.face.end()){
         tri::Allocator<MESH>::DeleteFace(m,*f);
         f++;
       }
-
-      VertexType::DeleteBitFlag(nmBit); // non manifoldness bit
     }
 
     template<class EAR>
@@ -504,7 +543,7 @@ template<class EAR>
         if(cb) (*cb)(indCb*10/vinfo.size(),"Closing Holes");
         if((*ith).size < sizeHole){
           holeCnt++;
-          FillHoleEar< EAR >(m, *ith,facePtrToBeUpdated);
+          FillHoleEar< EAR >(m, (*ith).p,facePtrToBeUpdated);
         }
       }
       return holeCnt;
@@ -555,7 +594,7 @@ template<class EAR>
           for(fpi=EAR::AdjacencyRing().begin();fpi!=EAR::AdjacencyRing().end();++fpi)
             facePtrToBeUpdated.push_back( &*fpi );
 
-          FillHoleEar<EAR >(m, *ith,facePtrToBeUpdated);
+          FillHoleEar<EAR >(m, ith->p,facePtrToBeUpdated);
           EAR::AdjacencyRing().clear();
         }
       }
@@ -871,7 +910,7 @@ template<class EAR>
     }while(sp != fp);
   }
   
-};//close class Hole
+};// class Hole
 
 } // end namespace tri
 } // end namespace vcg