Meaningful variable names and update doc.

Former-commit-id: 5b63d63031a04a7cb3a04fc9bf57b9043b77fbb2

include/igl/cgal/propagate_winding_numbers.cpp

@@ -60,13 +60,13 @@ IGL_INLINE bool igl::cgal::propagate_winding_numbers_single_component_patch_wise
         const Eigen::PlainObjectBase<DerivedF>& F,
         const Eigen::PlainObjectBase<DeriveduE>& uE,
         const std::vector<std::vector<uE2EType> >& uE2E,
-        const Eigen::PlainObjectBase<DerivedC>& C,
+        const Eigen::PlainObjectBase<DerivedC>& labels,
         const Eigen::PlainObjectBase<DerivedP>& P,
         const std::vector<std::vector<size_t> >& intersection_curves,
         Eigen::PlainObjectBase<DerivedW>& patch_W) {
     const size_t num_faces = F.rows();
     const size_t num_patches = P.maxCoeff() + 1;
-    assert(C.size() == num_patches);
+    assert(labels.size() == num_patches);
     // Utility functions.
     auto edge_index_to_face_index = [&](size_t ei) { return ei % num_faces; };
     auto edge_index_to_corner_index = [&](size_t ei) { return ei / num_faces; };
@@ -137,7 +137,7 @@ IGL_INLINE bool igl::cgal::propagate_winding_numbers_single_component_patch_wise
 
     // Propagate winding number from infinity.
     // Assuming infinity has winding number 0.
-    const size_t num_labels = C.maxCoeff() + 1;
+    const size_t num_labels = labels.maxCoeff() + 1;
     const int INVALID = std::numeric_limits<int>::max();
     patch_W.resize(num_patches, 2*num_labels);
     patch_W.setConstant(INVALID);
@@ -149,7 +149,7 @@ IGL_INLINE bool igl::cgal::propagate_winding_numbers_single_component_patch_wise
     igl::cgal::outer_facet(V, F, face_indices,
             outer_facet_idx, outer_facet_is_flipped);
     size_t outer_patch_idx = P[outer_facet_idx];
-    size_t outer_patch_label = C[outer_patch_idx];
+    size_t outer_patch_label = labels[outer_patch_idx];
     patch_W.row(outer_patch_idx).setZero();
     if (outer_facet_is_flipped) {
         patch_W(outer_patch_idx, outer_patch_label*2) = -1;
@@ -165,7 +165,7 @@ IGL_INLINE bool igl::cgal::propagate_winding_numbers_single_component_patch_wise
     Q.push(outer_patch_idx);
     while (!Q.empty()) {
         const size_t curr_patch_idx = Q.front();
-        const size_t curr_patch_label = C[curr_patch_idx];
+        const size_t curr_patch_label = labels[curr_patch_idx];
         Q.pop();
 
         const auto& adj_curves = patch_curve_adjacency[curr_patch_idx];
@@ -196,7 +196,7 @@ IGL_INLINE bool igl::cgal::propagate_winding_numbers_single_component_patch_wise
             if (!winding_num_assigned(next_patch_idx)) {
                 const bool next_ori = orientation[next_i];
                 const bool next_cons = next_ori != curr_ori;
-                const size_t next_patch_label = C[next_patch_idx];
+                const size_t next_patch_label = labels[next_patch_idx];
                 for (size_t i=0; i<num_labels; i++) {
                     const int shared_winding_number =
                         patch_W(curr_patch_idx, i*2);
@@ -223,7 +223,7 @@ IGL_INLINE bool igl::cgal::propagate_winding_numbers_single_component_patch_wise
             if (!winding_num_assigned(prev_patch_idx)) {
                 const bool prev_ori = orientation[prev_i];
                 const bool prev_cons = prev_ori != curr_ori;
-                const size_t prev_patch_label = C[prev_patch_idx];
+                const size_t prev_patch_label = labels[prev_patch_idx];
 
                 for (size_t i=0; i<num_labels; i++) {
                     const int shared_winding_number =
@@ -263,7 +263,7 @@ typename DerivedW>
 IGL_INLINE bool igl::cgal::propagate_winding_numbers_single_component(
         const Eigen::PlainObjectBase<DerivedV>& V,
         const Eigen::PlainObjectBase<DerivedF>& F,
-        const Eigen::PlainObjectBase<DerivedC>& C,
+        const Eigen::PlainObjectBase<DerivedC>& labels,
         Eigen::PlainObjectBase<DerivedW>& W) {
     typedef typename DerivedF::Scalar Index;
     const size_t num_faces = F.rows();
@@ -284,23 +284,23 @@ IGL_INLINE bool igl::cgal::propagate_winding_numbers_single_component(
     assert(P.size() == num_faces);
     assert(P.maxCoeff() + 1 == num_patches);
 
-    Eigen::VectorXi labels(num_patches);
+    Eigen::VectorXi patch_labels(num_patches);
     const int INVALID = std::numeric_limits<int>::max();
-    labels.setConstant(INVALID);
+    patch_labels.setConstant(INVALID);
     for (size_t i=0; i<num_faces; i++) {
-        if (labels[P[i]] == INVALID) {
-            labels[P[i]] = C[i];
+        if (patch_labels[P[i]] == INVALID) {
+            patch_labels[P[i]] = labels[i];
         } else {
-            assert(labels[P[i]] == C[i]);
+            assert(patch_labels[P[i]] == labels[i]);
         }
     }
-    assert((labels.array() != INVALID).all());
-    const size_t num_labels = labels.maxCoeff()+1;
+    assert((patch_labels.array() != INVALID).all());
+    const size_t num_labels = patch_labels.maxCoeff()+1;
 
     Eigen::MatrixXi winding_numbers;
     bool is_consistent =
         igl::cgal::propagate_winding_numbers_single_component_patch_wise(
-            V, F, uE, uE2E, labels, P, intersection_curves, winding_numbers);
+            V, F, uE, uE2E, patch_labels, P, intersection_curves, winding_numbers);
     assert(winding_numbers.rows() == num_patches);
     assert(winding_numbers.cols() == 2 * num_labels);
 
@@ -321,9 +321,9 @@ IGL_INLINE bool igl::cgal::propagate_winding_numbers_single_component(
         const Eigen::PlainObjectBase<DerivedF>& F,
         Eigen::PlainObjectBase<DerivedW>& W) {
     const size_t num_faces = F.rows();
-    Eigen::VectorXi C(num_faces);
-    C.setZero();
-    return igl::cgal::propagate_winding_numbers_single_component(V, F, C, W);
+    Eigen::VectorXi labels(num_faces);
+    labels.setZero();
+    return igl::cgal::propagate_winding_numbers_single_component(V, F, labels, W);
 }
 
 template<

include/igl/cgal/propagate_winding_numbers.h

@@ -4,17 +4,38 @@
 #include <Eigen/Core>
 #include <vector>
 
+// The following methods compute the winding number on each side of each facet
+// or patch of a 3D mesh.  The input mesh is valid if it splits the ambient
+// space, R^3, into subspaces with constant integer winding numbers.  That is
+// the input mesh should be closed and for each directed edge the number of
+// clockwise facing facets should equal the number of counterclockwise facing
+// facets.
+
 namespace igl {
     namespace cgal {
-        // Computer winding number on each side of each patch.
+        // Compute winding number on each side of each patch.  All patches must
+        // be connected.  The per-patch label partitions the patches into
+        // different components, and winding number is computed for each
+        // component.  For example, ``patch_W(i, j*2)`` for ``i`` in [0, #P)
+        // and ``j`` in [0, k) is the winding number on the positive side of
+        // patch ``i`` with respect to component ``j``.  Similarly,
+        // ``patch_W(i, j*2+1)`` is the winding number on the negative side of
+        // patch ``i`` with respect to component ``j``.
+        //
+        // Patch and intersection curve can be generated using:
+        // ``igl::extract_manifold_patches(...)`` and
+        // ``igl::extract_non_manifold_edge_curves(...)``
+        //
         //
         // Inputs:
         //   V  #V by 3 list of vertices.
-        //   F  #F by 3 list of trinalges.
+        //   F  #F by 3 list of trianlges.
         //   uE #uE by 2 list of undirected edges.
         //   uE2E  #uE list of lists mapping each undirected edge to directed
         //         edges.
-        //   C  #P list of component indices.
+        //   labels  #P list of labels, ranging from 0 to k-1.
+        //           These labels partition patches into k components, and
+        //           winding number is computed for each component.
         //   P  #F list of patch indices.
         //   intersection_curves  A list of non-manifold curves that separates
         //                        the mesh into patches.
@@ -22,6 +43,9 @@ namespace igl {
         // Outputs:
         //   patch_W  #P by k*2 list of winding numbers on each side of a
         //            patch for each component.
+        //
+        // Returns:
+        //   True iff integer winding numbers can be consistently assigned.
         template<
             typename DerivedV,
             typename DerivedF,
@@ -35,26 +59,25 @@ namespace igl {
                 const Eigen::PlainObjectBase<DerivedF>& F,
                 const Eigen::PlainObjectBase<DeriveduE>& uE,
                 const std::vector<std::vector<uE2EType> >& uE2E,
-                const Eigen::PlainObjectBase<DerivedC>& C,
+                const Eigen::PlainObjectBase<DerivedC>& labels,
                 const Eigen::PlainObjectBase<DerivedP>& P,
                 const std::vector<std::vector<size_t> >& intersection_curves,
                 Eigen::PlainObjectBase<DerivedW>& patch_W);
 
-        // Compute winding number on each side of the face.
-        //
-        // This method assumes the input mesh (V, F, I) forms a single connected
-        // component.
+        // Compute winding number on each side of the face.  The input mesh must
+        // be a single edge-connected component.
         //
         // Inputs:
         //   V  #V by 3 list of vertex positions.
         //   F  #F by 3 list of triangle indices into V.
-        //   C  #F list of effective face indices ranging from 0 to k-1.
+        //   labels  #F list of facet labels ranging from 0 to k-1.
         //
         // Output:
-        //   W  #F by 2*k list of winding numbers.  W(i,2*j) is the winding
-        //   number of submesh j on the positive side of facet i, and
-        //   W(i, 2*j+1) is the winding number of submesh j on the negative
-        //   side of facet i.
+        //   W  #F by 2*k list of winding numbers.
+        //      ``W(i, 2*j)`` is the winding number on the positive side of
+        //      facet ``i`` with respect to facets labelled ``j``.
+        //      ``W(i, 2*j+1)`` is the winding number on the negative side of
+        //      facet ``i`` with respect to facets labelled ``j``.
         //
         // Returns:
         //   True iff integer winding number can be consistently assigned.
@@ -66,7 +89,7 @@ namespace igl {
         IGL_INLINE bool propagate_winding_numbers_single_component(
                 const Eigen::PlainObjectBase<DerivedV>& V,
                 const Eigen::PlainObjectBase<DerivedF>& F,
-                const Eigen::PlainObjectBase<DerivedC>& C,
+                const Eigen::PlainObjectBase<DerivedC>& labels,
                 Eigen::PlainObjectBase<DerivedW>& W);
 
         // Compute the winding number on each side of the face.
@@ -81,6 +104,9 @@ namespace igl {
         //   W  #F by 2 list of winding numbers.  W(i,0) is the winding number
         //   on the positive side of facet i, and W(i, 1) is the winding
         //   number on the negative side of facet I[i].
+        //
+        // Returns:
+        //   True iff integer winding number can be consistently assigned.
         template<
             typename DerivedV,
             typename DerivedF,
@@ -92,18 +118,20 @@ namespace igl {
 
         // Compute winding number on each side of the face.  The input mesh
         // could contain multiple connected components.  The input mesh must
-        // representa the boundary of a valid 3D volume, which means it is
+        // represent the boundary of a valid 3D volume, which means it is
         // closed, consistently oriented and induces integer winding numbers.
         //
         // Inputs:
         //   V  #V by 3 list of vertex positions.
         //   F  #F by 3 list of triangle indices into V.
-        //   C  #F list of facet labels.
+        //   labels  #F list of facet labels ranging from 0 to k-1.
         //
         // Output:
-        //   W  #I by 2 list of winding numbers.  W(i,0) is the winding number
-        //   on the positive side of facet I[i], and W(i, 1) is the winding
-        //   number on the negative side of facet I[i].
+        //   W  #F by k*2 list of winding numbers.  ``W(i,j*2)`` is the winding
+        //      number on the positive side of facet ``i`` with respect to the
+        //      facets labeled ``j``.  Similarly, ``W(i,j*2+1)`` is the winding
+        //      number on the negative side of facet ``i`` with respect to the
+        //      facets labeled ``j``.
         template<
             typename DerivedV,
             typename DerivedF,